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 `: Output file path
• `--all`: Capture all monitors (full mode only)
• `--monitor `: 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