mcp-screenshot-server

MCP Screenshot Server

A modular MCP (Model Context Protocol) solution for capturing screenshots on both local and remote machines through Claude Code, using secure tunnels for communication.

Features

• Dual Instance Architecture: Run separate MCP server instances on local and remote machines
• Secure Communication: Uses ngrok tunnels with HMAC authentication
• Flexible Screenshot Capture:
  • Fullscreen screenshots
  • Window-specific screenshots (by window name)
  • Support for macOS, Windows, and Linux
• Transparent Operation: LLM can simply specify "local" or "remote" targets

Prerequisites

• Node.js 18+
• Claude Code or any MCP-compatible client

Installation

• Clone the repository:

git clone <repository-url>
cd mcp-local-remote-screenshot

• Install dependencies:

npm install

• Build the project:

npm run build

Configuration

1. Environment Setup

Create .env files for both local and remote instances:

For Remote Instance (.env.remote):

INSTANCE_TYPE=remote
SHARED_SECRET=your-secure-shared-secret-here
WEBSOCKET_PORT=8765
LOCALTUNNEL_SUBDOMAIN=my-screenshot-server  # Optional: for consistent URL

For Local Instance (.env.local):

INSTANCE_TYPE=local
SHARED_SECRET=your-secure-shared-secret-here
REMOTE_TUNNEL_URL=wss://xxxxx.loca.lt  # Will be provided by remote instance

2. Claude Code Integration

Add to your Claude Code configuration:

{
  "mcpServers": {
    "screenshot": {
      "command": "node",
      "args": ["/path/to/mcp-screenshot-server/dist/index.js"],
      "env": {
        "INSTANCE_TYPE": "local",
        "SHARED_SECRET": "your-secure-shared-secret",
        "REMOTE_TUNNEL_URL": "wss://your-tunnel.loca.lt"
      }
    }
  }
}

Running the Servers

Remote Server Setup

• On the remote machine, start the server:

npm run remote
# or with custom env file
node dist/index.js --env .env.remote

• Note the tunnel URL displayed in the console:

LocalTunnel created: wss://xxxxx.loca.lt

• Add this URL to your local instance's configuration.

Local Server Setup

• Update the REMOTE_TUNNEL_URL in your local .env file
• Start the local server:

npm run local
# or
node dist/index.js --env .env.local

Usage Examples

Once both servers are running and Claude Code is configured, the LLM can use these commands:

1. Capture Local Fullscreen

Use the screenshot tool to capture a fullscreen screenshot from the local machine

2. Capture Remote Fullscreen

Use the screenshot tool to capture a fullscreen screenshot from the remote machine

3. Capture Specific Window (Local)

Use the screenshot tool to capture the "Simulator" window from the local machine

4. Capture Specific Window (Remote)

Use the screenshot tool to capture the "Chrome" window from the remote machine

Architecture

┌─────────────────┐         ┌─────────────────┐
│  Local Machine  │         │ Remote Machine  │
│                 │         │                 │
│  ┌───────────┐  │         │  ┌───────────┐  │
│  │    MCP    │  │ WebSocket  │    MCP    │  │
│  │  Server   │◄─┼─────────┼─►│  Server   │  │
│  │ (Local)   │  │   WSS    │  │ (Remote)  │  │
│  └─────┬─────┘  │         │  └─────┬─────┘  │
│        │        │         │        │        │
│  ┌─────▼─────┐  │         │  ┌─────▼─────┐  │
│  │Screenshot │  │         │  │Screenshot │  │
│  │ Service   │  │         │  │ Service   │  │
│  └───────────┘  │         │  └───────────┘  │
└─────────────────┘         └─────────────────┘
         ▲                           ▲
         │                           │
         └───────────┬───────────────┘
                     │
              ┌──────▼──────┐
              │ Claude Code │
              │     LLM     │
              └─────────────┘

Security

• HMAC Authentication: All commands are authenticated using HMAC-SHA256
• Time-based Validation: Auth tokens expire after 5 minutes
• Shared Secret: Must be the same on both instances
• Tunnel Security: LocalTunnel provides HTTP/WebSocket tunnels

Troubleshooting

Connection Issues

• Ensure both servers are running
• Verify the tunnel URL is correctly set in the local instance
• Check firewall settings for WebSocket connections

Screenshot Failures

• Window not found: Ensure the window name matches exactly
• Permission denied: Grant screen recording permissions (macOS)
• Platform issues: Some features may require platform-specific setup

Authentication Errors

• Verify both instances use the same SHARED_SECRET
• Ensure system clocks are synchronized (within 5 minutes)

Development

Project Structure

src/
├── core/
│   └── mcp-server.ts      # Main MCP server implementation
├── services/
│   ├── screenshot.ts      # Screenshot capture service
│   └── tunnel.ts          # Tunnel and communication service
├── types/
│   └── index.ts          # TypeScript type definitions
└── index.ts              # Entry point

Running in Development

npm run dev

License

MIT