# 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](https://ampcode.com) 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:
```bash
git clone https://github.com/Kynlos/desktop-window-screenshot-mcp.git
cd desktop-window-screenshot-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
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:

```json
{
  "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:**
```javascript
// 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:**
```javascript
// 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:**
```javascript
{ "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
```bash
# Run in development mode
npm run dev

# Build for production
npm run build

# Test the server
npm test
```

### Testing
```bash
# 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:
```bash
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](LICENSE) file for details.

## Author

**Kynlo**

Built for [Amp](https://ampcode.com) - The AI-powered coding assistant.

## Repository

[https://github.com/Kynlos/desktop-window-screenshot-mcp](https://github.com/Kynlos/desktop-window-screenshot-mcp)