Desktop Window Screenshot MCP

A Model Context Protocol (MCP) Server that provides cross-platform desktop and window screenshot capabilities with automatic clipboard integration.

Built for Amp but compatible with any MCP client.

Features

• 📸 Full desktop screenshots - Capture entire screen
• 🪟 Window targeting - Target specific windows by ID or title
• 📋 Automatic clipboard - Screenshots automatically copied to clipboard
• 🖥️ Cross-platform - Windows, macOS, and Linux support
• 🔍 Window discovery - List all available windows
• 📊 Multiple formats - PNG and JPEG with quality control
• 🎯 MCP integration - Ready for AI coding assistants

Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/Kynlos/desktop-window-screenshot-mcp.git
cd desktop-window-screenshot-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage with Amp

Setup in Amp (Recommended)

1. Open Amp (VSCode with Amp extension)
2. Access MCP Server settings
3. Click "Add MCP Server"
4. Configure as follows:

Server Name:

Screenshot

Command or URL:

npx

Arguments (whitespace-separated):

tsx "C:\Users\YourUsername\path\to\desktop-window-screenshot-mcp\src\index.ts"

Replace C:\Users\YourUsername\path\to\desktop-window-screenshot-mcp with your actual project path.

Alternative Setup Methods

Method 1 - Using npm start:

Command: npm
Arguments: --prefix "C:\Users\YourUsername\path\to\desktop-window-screenshot-mcp" start

Method 2 - Using built JavaScript:

Command: node
Arguments: "C:\Users\YourUsername\path\to\desktop-window-screenshot-mcp\dist\index.js"

Example Path Configurations

Windows:

C:\Users\john\Documents\desktop-window-screenshot-mcp\src\index.ts

macOS/Linux:

/Users/john/projects/desktop-window-screenshot-mcp/src/index.ts

Usage with Other MCP Clients

Configuration for generic MCP clients:

{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": ["tsx", "/path/to/desktop-window-screenshot-mcp/src/index.ts"]
    }
  }
}

Available Tools

📸 take_screenshot

Take a screenshot of the entire desktop or specific window.

Parameters:

• windowId (optional): Window ID to screenshot (from list_windows)
• format (optional): 'png' or 'jpg' (default: 'png')
• quality (optional): 1-100 (default: 90, only for JPEG)
• copyToClipboard (optional): boolean (default: true)

Example:

// Full desktop screenshot
{ "name": "take_screenshot" }

// Specific window screenshot  
{ "name": "take_screenshot", "arguments": { "windowId": 12345 } }

🪟 take_window_screenshot

Take a screenshot by searching for a window title.

Parameters:

• windowTitle (required): Part of window title to search for (case-insensitive)
• format (optional): 'png' or 'jpg' (default: 'png')
• quality (optional): 1-100 (default: 90)

Example:

// Screenshot Notepad window
{ "name": "take_window_screenshot", "arguments": { "windowTitle": "Notepad" } }

// Screenshot browser with specific quality
{ 
  "name": "take_window_screenshot", 
  "arguments": { 
    "windowTitle": "Chrome", 
    "format": "jpg", 
    "quality": 85 
  } 
}

🔍 list_windows

List all visible windows with their IDs and titles.

Example:

{ "name": "list_windows" }

Returns:

Found 15 visible windows:
- ID: 12345, Title: "Document.txt - Notepad", Process: notepad.exe (PID: 1234)
- ID: 67890, Title: "Google Chrome", Process: chrome.exe (PID: 5678)
...

Platform Support

Platform	Status	Notes
Windows	✅ Full Support	Native Windows APIs, all features
macOS	✅ Full Support	Native macOS APIs, all features
Linux	✅ Full Support	X11/Wayland support, all features

Development

Local Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Test the server
npm test

Testing

# Basic functionality test
npm test

# Manual testing
node test-server.js

Troubleshooting

Common Issues

"Module not found" errors:

• Ensure you're using the full absolute path in the Arguments field
• Use forward slashes / instead of backslashes \ on Windows if needed
• Verify Node.js and npm are installed correctly

"Window not found" errors:

• Use list_windows first to see available windows
• Window titles are case-sensitive for exact matches
• Try partial title matches (e.g., "Notepad" instead of "Document.txt - Notepad")

Permission errors:

• On macOS/Linux: Grant screen recording permissions if prompted
• On Windows: Run as administrator if needed for certain applications

Debug Mode

Enable debug logging by setting environment variable:

DEBUG=1 npm start

Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• screenshot-desktop - Cross-platform screenshot capture
• clipboardy - Cross-platform clipboard access
• node-window-manager - Window enumeration and management
• node-screenshots - Advanced window screenshot capabilities
• sharp - Image processing and format conversion

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature-name
5. Submit a Pull Request

License

MIT License - see LICENSE file for details.

Author

Kynlo

Built for Amp - The AI-powered coding assistant.

Repository

https://github.com/Kynlos/desktop-window-screenshot-mcp