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.12Install 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:
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:
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-controlRun the server with SSE transport:
mcp-control --sseNote 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:
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:
Or use modular configuration for specific operations:
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:
📚 Dependencies
@modelcontextprotocol/sdk - MCP SDK for protocol implementation
keysender - Windows-only UI automation library
clipboardy - Clipboard handling
sharp - Image processing
uuid - UUID generation
🚧 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
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Windows control server for the Model Context Protocol, providing programmatic control over system operations including mouse, keyboard, window management, and screen capture functionality.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that provides programmatic access to the Windows terminal, enabling AI models to interact with the Windows command line through standardized tools for writing commands, reading output, and sending control signals.Last updated -3MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that provides secure command-line access to Windows systems, allowing MCP clients like Claude Desktop to safely execute commands in PowerShell, CMD, and Git Bash shells with configurable security controls.Last updated -9215249MIT License
- -securityAlicense-qualityA Model Context Protocol server that wraps AutoIt functionality, enabling LLMs to automate Windows desktop tasks including mouse/keyboard operations, window management, and UI control interactions.Last updated -92MIT License
- -securityAlicense-qualityMCP server that provides computer control capabilities including mouse movements, keyboard actions, screenshot capture with OCR, and window management through a unified API.Last updated -44MIT License