MCPControl
Windows control server for the Model Context Protocol, 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
- Install Build Tools (including VC++ workload)
# 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"
- Install Python (if not already installed)
# Install Python (required for node-gyp)
winget install Python.Python.3.12
- Install Node.js
# Install latest LTS version
winget install OpenJS.NodeJS
Installation
- Install MCPControl Package
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:
{
"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:
{
"mcpServers": {
"MCPControl": {
"command": "mcp-control",
"args": ["--sse"]
}
}
}
Starting the Server
First, start the MCPControl server on your VM or local machine:
The server will display:
- Available network interfaces and their IP addresses
- The port number (default: 3232)
- Connection status messages
VM Setup Example
- Start your Windows VM with 1280x720 resolution
- Install MCPControl on the VM:
npm install -g mcp-control
- Run the server with SSE transport:
- Note the VM's IP address (e.g.,
192.168.1.100) - Configure Claude with the SSE URL:
{
"mcpServers": {
"MCPControl": {
"transport": "sse",
"url": "http://192.168.1.100:3232/mcp"
}
}
}
- Restart Claude and MCPControl will appear in your MCP menu!
🔧 CLI Options
MCPControl supports several command-line flags for advanced configurations:
# 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 Claude can see your screen and help with complex tasks
Development and Testing
- Cross-Application Integration: Bridge applications that don't normally communicate
- UI Testing Framework: Create robust testing scenarios with visual validation
- Demo Creation: Automate the creation of product demonstrations
⚠️ IMPORTANT DISCLAIMER
THIS SOFTWARE IS EXPERIMENTAL AND POTENTIALLY DANGEROUS
By using this software, you acknowledge and accept that:
- Giving AI models direct control over your computer through this tool is inherently risky
- This software can control your mouse, keyboard, and other system functions which could potentially cause unintended consequences
- You are using this software entirely at your own risk
- The creators and contributors of this project accept NO responsibility for any damage, data loss, or other consequences that may arise from using this software
- This tool should only be used in controlled environments with appropriate safety measures in place
USE AT YOUR OWN RISK
🌟 Features
🔧 Automation Providers
MCPControl supports multiple automation providers for different use cases:
- keysender (default) - Native Windows automation with high reliability
- powershell - Windows PowerShell-based automation for simpler operations
- autohotkey - AutoHotkey v2 scripting for advanced automation needs
Provider Configuration
You can configure the automation provider using environment variables:
# Use a specific provider for all operations
export AUTOMATION_PROVIDER=autohotkey
# Configure AutoHotkey executable path (if not in PATH)
export AUTOHOTKEY_PATH="C:\Program Files\AutoHotkey\v2\AutoHotkey.exe"
Or use modular configuration for specific operations:
# Mix and match providers for different operations
export AUTOMATION_KEYBOARD_PROVIDER=autohotkey
export AUTOMATION_MOUSE_PROVIDER=keysender
export AUTOMATION_SCREEN_PROVIDER=keysender
export AUTOMATION_CLIPBOARD_PROVIDER=powershell
See provider-specific documentation:
🛠️ Development Setup
If you're interested in contributing or building from source, please see CONTRIBUTING.md for detailed instructions.
Development Requirements
To build this project for development, you'll need:
- Windows operating system (required for the keysender dependency)
- Node.js 18 or later (install using the official Windows installer which includes build tools)
- npm package manager
- Native build tools:
- node-gyp:
npm install -g node-gyp - cmake-js:
npm install -g cmake-js
The keysender dependency relies on Windows-specific native modules that require these build tools.
📋 Project Structure
/src/handlers - Request handlers and tool management/tools - Core functionality implementations/types - TypeScript type definitionsindex.ts - Main application entry point
🔖 Repository Branches
main - Main development branch with the latest features and changesrelease - Stable release branch that mirrors the latest stable tag (currently v0.2.0)
Version Installation
You can install specific versions of MCPControl using npm:
# Install the latest stable release (from release branch)
npm install mcp-control
# Install a specific version
npm install mcp-control@0.1.22
📚 Dependencies
🚧 Known Limitations
- Window minimize/restore operations are currently unsupported
- Multiple screen functions may not work as expected, depending on setup
- The get_screenshot utility does not work with the VS Code Extension Cline. See GitHub issue #1865
- Some operations may require elevated permissions depending on the target application
- Only Windows is supported
- MCPControl works best at 1280x720 resolution, single screen. Click accuracy is optimized for this resolution. We're working on an offset/scaling bug and looking for testers or help creating testing tools
👥 Contributing
See CONTRIBUTING.md
⚖️ License
This project is licensed under the MIT License - see the LICENSE file for details.
📖 References