MCPControl

# MCPControl <p align="center"> <img src="https://github.com/user-attachments/assets/1c577e56-7b8d-49e9-aaf5-b8550cc6cfc0" alt="MCPControl Logo" width="250"> </p> <p align="center"> <a href="https://github.com/Cheffromspace/MCPControl/releases/tag/v0.2.0"> <img src="https://img.shields.io/badge/release-v0.2.0-blue.svg" alt="Latest Release"> </a> </p> Windows control server for the [Model Context Protocol](https://modelcontextprotocol.io/), providing programmatic control over system operations including mouse, keyboard, window management, and screen capture functionality. > **Note**: This project currently supports Windows only. ## 🔥 Why MCPControl? MCPControl bridges the gap between AI models and your desktop, enabling secure, programmatic control of: - 🖱️ **Mouse movements and clicks** - ⌨️ **Keyboard input and shortcuts** - 🪟 **Window management** - 📸 **Screen capture and analysis** - 📋 **Clipboard operations** ## 🔌 Quick Start ### Prerequisites 1. **Install Build Tools (including VC++ workload)** ```powershell # Run as Administrator - may take a few minutes to complete winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" ``` 2. **Install Python** (if not already installed) ```powershell # Install Python (required for node-gyp) winget install Python.Python.3.12 ``` 3. **Install Node.js** ```powershell # Install latest LTS version winget install OpenJS.NodeJS ``` ### Installation 1. **Install MCPControl Package** ```powershell npm install -g mcp-control ``` ### Configuration MCPControl works best in a **virtual machine at 1280x720 resolution** for optimal click accuracy. Configure your Claude client to connect to MCPControl via SSE transport: #### Option 1: Direct SSE Connection For connecting to an MCPControl server running on a VM or remote machine: ```json { "mcpServers": { "MCPControl": { "transport": "sse", "url": "http://192.168.1.100:3232/mcp" } } } ``` Replace `192.168.1.100:3232` with your server's IP address and port. #### Option 2: Local Launch with SSE To launch MCPControl locally with SSE transport: ```json { "mcpServers": { "MCPControl": { "command": "mcp-control", "args": ["--sse"] } } } ``` ### Starting the Server First, start the MCPControl server on your VM or local machine: ```bash mcp-control --sse ``` The server will display: - Available network interfaces and their IP addresses - The port number (default: 3232) - Connection status messages ### VM Setup Example 1. **Start your Windows VM** with 1280x720 resolution 2. **Install MCPControl** on the VM: ```bash npm install -g mcp-control ``` 3. **Run the server** with SSE transport: ```bash mcp-control --sse ``` 4. **Note the VM's IP address** (e.g., `192.168.1.100`) 5. **Configure Claude** with the SSE URL: ```json { "mcpServers": { "MCPControl": { "transport": "sse", "url": "http://192.168.1.100:3232/mcp" } } } ``` 6. **Restart Claude** and MCPControl will appear in your MCP menu! ## 🔧 CLI Options MCPControl supports several command-line flags for advanced configurations: ```bash # Run with SSE transport on default port (3232) mcp-control --sse # Run with SSE on custom port mcp-control --sse --port 3000 # Run with HTTPS/TLS (required for production deployments) mcp-control --sse --https --cert /path/to/cert.pem --key /path/to/key.pem # Run with HTTPS on custom port mcp-control --sse --https --port 8443 --cert /path/to/cert.pem --key /path/to/key.pem ``` ### Command Line Arguments - `--sse` - Enable SSE (Server-Sent Events) transport for network access - `--port [number]` - Specify custom port (default: 3232) - `--https` - Enable HTTPS/TLS (required for remote deployments per MCP spec) - `--cert [path]` - Path to TLS certificate file (required with --https) - `--key [path]` - Path to TLS private key file (required with --https) ### Security Note According to the MCP specification, HTTPS is **mandatory** for all HTTP-based transports in production environments. When deploying MCPControl for remote access, always use the `--https` flag with valid TLS certificates. ## 🚀 Popular Use Cases ### Assisted Automation - **Application Testing**: Delegate repetitive UI testing to Claude, allowing AI to navigate through applications and report issues - **Workflow Automation**: Have Claude operate applications on your behalf, handling repetitive tasks while you focus on creative work - **Form Filling**: Let Claude handle data entry tasks with your supervision ### AI Experimentation - **AI Gaming**: Watch Claude learn to play simple games through visual feedback - **Visual Reasoning**: Test Claude's ability to navigate visual interfaces and solve visual puzzles - **Human-AI Collaboration**: Explore new interaction paradigms where Cl