This repo is in Read Only mode and has been replaced

Use the WSLSnapIt-MCP repo instead (works better, more features!)

Screenshot MCP Server

A Model Context Protocol (MCP) server that enables AI assistants running in WSL to capture Windows screenshots with advanced features like monitor selection and window-specific capture.

Features

• 📸 Full Desktop Capture - Capture all monitors (default behavior)
• 🖥️ Monitor Selection - Capture specific monitors (primary, 1, 2, etc.)
• 🪟 Window Capture - Capture specific windows by title match with DPI awareness
• 🚀 Process Capture - Capture windows by process name (e.g., notepad.exe)
• 📂 Custom Save Locations - Save to any folder using WSL or Windows paths
• 🔄 Automatic Path Conversion - Converts WSL paths to Windows paths
• 📁 Organized Storage - Screenshots saved to workspace/screenshots/ by default
• 🎯 DPI Aware - Proper scaling for high-DPI displays
• 🖼️ Full Window Capture - Includes window shadows and borders without clipping

API Reference

The MCP server provides a single tool:

take_screenshot

Parameters:

• filename (optional): Name for the screenshot file (default: "screenshot.png")
• monitor (optional): Which monitor to capture
  • "all" - Capture all monitors (default)
  • "primary" - Capture primary monitor only
  • 1, 2, etc. - Capture specific monitor by index
• windowTitle (optional): Capture a specific window by its title (partial match supported)
• processName (optional): Capture a specific window by process name (e.g., "notepad.exe" or "notepad")
• folder (optional): Custom folder path to save the screenshot
  • Supports WSL paths: /mnt/c/Users/...
  • Supports Windows paths: C:\Users\...
  • Supports relative paths: ../images
  • Default: workspace/screenshots/

Returns:

• Success message with the file path
• Error message if capture fails

Notes:

• If both windowTitle and processName are provided, windowTitle takes precedence
• Custom folders are created automatically if they don't exist
• Path formats are automatically converted between WSL and Windows as needed

Technical Details

Architecture

• MCP Server: Node.js with @modelcontextprotocol/sdk
• Screenshot Capture: PowerShell with .NET Windows Forms
• Communication: Executes PowerShell commands from WSL
• Encoding: Base64 encoding for reliable command execution

Window Capture Features

• DPI Awareness: Automatically handles high-DPI displays for crisp captures
• Window Padding: Adds 10px padding to capture window shadows and borders
• Render Wait: Waits 200ms after focusing window to ensure complete rendering
• Bounds Checking: Prevents negative coordinates when windows are near screen edges
• Process Matching: Intelligent process name matching (strips .exe extension automatically)

How It Works

1. MCP server receives screenshot request from Claude
2. Determines save location (custom folder or default)
3. Converts paths between WSL and Windows formats as needed
4. Constructs appropriate PowerShell script based on parameters
5. Encodes script in base64 to avoid escaping issues
6. Executes PowerShell command from WSL
7. PowerShell captures screenshot using Windows Forms APIs
8. Image is saved to the specified location

Error Handling

• Filters PowerShell CLIXML output (verbose logging, not errors)
• Validates monitor indices
• Provides clear error messages for missing windows or processes
• Lists available windows when capture fails
• Automatically creates directories if needed
• Handles both WSL and Windows path formats

Recent Updates

v1.2.0

• Added custom folder support with the folder parameter
• Supports both WSL paths (/mnt/...) and Windows paths (C:\...)
• Automatic path conversion between WSL and Windows formats
• Creates custom directories automatically if they don't exist
• Maintains backward compatibility with default screenshots folder

v1.1.0

• Added process name capture support
• Can now capture windows by process name (e.g., "notepad.exe")
• Intelligent .exe extension handling
• Enhanced error messages showing available windows

v1.0.1

• Fixed window capture clipping issues
• Added DPI awareness for high-DPI displays
• Added padding to capture window shadows
• Improved window rendering wait time
• Added bounds checking for edge cases

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

• Built for use with Claude Desktop and Claude Code
• Uses the Model Context Protocol
• Special thanks to the WSL team for making Windows/Linux integration possible

Prerequisites

• Windows with WSL (Windows Subsystem for Linux)
• Node.js installed in WSL
• Claude Desktop or Claude Code with MCP support

Installation

1. Clone this repository:

git clone https://github.com/peterparker57/screenshot-mcp.git
cd screenshot-mcp

2. Install dependencies:

npm install
# or with bun:
bun install

3. Add to your Claude configuration (~/.claude.json or ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "screenshot": {
      "command": "node",
      "args": [
        "/path/to/screenshot-mcp/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "take_screenshot"
      ]
    }
  }
}

4. Restart Claude Desktop/Code

Usage

Once installed, you can ask Claude to take screenshots:

Basic Usage

Take a screenshot

Capture Specific Monitor

Take a screenshot of monitor 1
Take a screenshot of the primary monitor

Capture Specific Window by Title

Take a screenshot of the "Chrome" window
Take a screenshot of window titled "Visual Studio Code"

Capture Specific Window by Process Name

Take a screenshot of notepad.exe
Take a screenshot of the chrome process
Take a screenshot of process "Code"

Custom Filename

Take a screenshot and save it as "test.png"

Save to Custom Folder

Take a screenshot and save it to /mnt/c/Users/username/Pictures/
Take a screenshot and save to C:\Users\username\Desktop\
Take a screenshot of monitor 1 and save to folder "../docs/images"

Troubleshooting

Screenshots folder not created

The server automatically creates folders as needed. Ensure you have write permissions to the target location.

PowerShell execution errors

Check your PowerShell execution policy:

Get-ExecutionPolicy

Window not found errors

• Ensure the window is open and not minimized
• The title match is case-insensitive and supports partial matches
• Try using a more specific window title
• When searching by process, the tool will list all available windows to help you identify the correct one

Window capture is clipped

The latest version includes automatic padding and DPI awareness. If you still experience clipping:

• Ensure you're using the latest version
• Try maximizing the window before capture
• Check if the window has unusual rendering (some apps use custom chrome)

Path conversion issues

The server automatically converts between WSL and Windows path formats:

• WSL paths like /mnt/c/... are converted to C:\... for PowerShell
• Windows paths like C:\... are converted to /mnt/c/... for file verification
• Ensure your paths are accessible from both WSL and Windows