MCP Windows Screenshots

A Model Context Protocol (MCP) server that provides screenshot capture functionality on Windows systems.

Features

• Full-screen screenshots: Capture entire monitors or all monitors
• Region screenshots: Interactive area selection for targeted captures
• Screenshot management: List and manage captured screenshots
• Image embedding: Optional base64 image embedding in MCP responses
• Cross-monitor support: Handle multi-monitor setups

Prerequisites

• Windows OS (currently Windows-only)
• Node.js >= 18.0.0
• Helper executable: A Windows executable (RegionSnip.exe) that handles the actual screenshot capture

Installation

1. Clone the repository

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Ensure the helper executable exists at bin/RegionSnip.exe

Usage

As an MCP Server

This server communicates via stdio and can be used with any MCP-compatible client (like Claude Desktop).

Start the server:

npm start

Or with the MCP inspector for debugging:

npm run inspector

Usage with npx

You can run this MCP server directly using npx without installing it globally:

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "windows-screenshots": {
      "command": "npx",
      "args": ["mcp-windows-screenshot"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "windows-screenshots": {
      "command": "npx",
      "args": ["mcp-windows-screenshot"]
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "windows-screenshots": {
      "command": "npx",
      "args": ["mcp-windows-screenshot"]
    }
  }
}

Available Tools

takeScreenshot

Captures a full-screen screenshot.

Parameters:

• mode: Always "full" (default)
• allMonitors: Capture all monitors (default: true)
• monitor: Specific monitor number (optional)
• includeImage: Embed image as base64 in response (default: false)
• timeoutMs: Timeout in milliseconds (default: 60000)

Example:

{
  "mode": "full",
  "allMonitors": true,
  "includeImage": true
}

Response:

{
  "ok": true,
  "cancelled": false,
  "path": "screenshots/full-2024-01-14T10-53-52-000Z.png",
  "rect": {"x": 0, "y": 0, "width": 1920, "height": 1080},
  "width": 1920,
  "height": 1080,
  "mode": "full",
  "allMonitors": true,
  "monitor": null
}

takeSelectedAreaScreenshot

Allows interactive selection of a screen region to capture.

Parameters:

• mode: Always "region" (default)
• includeImage: Embed image as base64 in response (default: false)
• timeoutMs: Timeout in milliseconds (default: 120000)

Example:

{
  "includeImage": true
}

Response:

{
  "ok": true,
  "cancelled": false,
  "path": "screenshots/region-2024-01-14T10-53-52-000Z.png",
  "rect": {"x": 100, "y": 100, "width": 800, "height": 600},
  "width": 800,
  "height": 600,
  "mode": "region"
}

listScreenshots

Lists saved screenshots in the screenshots directory.

Parameters:

• limit: Maximum number of screenshots to return (default: 50, max: 200)

Example:

{
  "limit": 10
}

Response:

{
  "items": [
    {
      "path": "screenshots/region-2024-01-14T10-53-52-000Z.png",
      "sizeBytes": 245760,
      "createdAt": "2024-01-14T10:53:52.000Z"
    }
  ]
}

Configuration

Helper Executable

The server requires a helper executable at bin/RegionSnip.exe that supports the following command-line arguments:

• --mode full|region: Capture mode
• --out <path>: Output file path
• --all: Capture all monitors (full mode only)
• --monitor <n>: Specific monitor number (full mode only)

The executable should output JSON to stdout with the following structure:

{
  "ok": true,
  "cancelled": false,
  "rect": {"x": 0, "y": 0, "width": 1920, "height": 1080},
  "width": 1920,
  "height": 1080
}

Screenshots Directory

Screenshots are automatically saved to the screenshots/ directory in the project root. This directory is created automatically if it doesn't exist.

Development

Building

npm run build

Testing

The server can be tested using the MCP inspector:

npm run inspector

This starts the server and opens a debugging interface to test the available tools.

Project Structure

├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── screenshots/          # Screenshot storage directory
├── bin/
│   └── RegionSnip.exe    # Helper executable (not included)
├── package.json
└── README.md