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.
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
-
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
-
Install MCPControl Package
npm install -g mcp-control
MCPControl works best in a virtual machine at 1280x720 resolution for optimal click accuracy.
Configure your Claude client to use the SSE transport:
{
"mcpServers": {
"MCPControl": {
"command": "mcp-control",
"args": [
"--transport",
"sse"
]
}
}
}You can also run the server directly with SSE:
mcp-control --transport sseRestart your client and MCPControl will appear in your MCP menu!
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-
--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)
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.
- 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 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
- 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
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
|
|
|
|
If you're interested in contributing or building from source, please see CONTRIBUTING.md for detailed instructions.
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
- node-gyp:
The keysender dependency relies on Windows-specific native modules that require these build tools.
-
/src-
/handlers- Request handlers and tool management -
/tools- Core functionality implementations -
/types- TypeScript type definitions -
index.ts- Main application entry point
-
-
main- Main development branch with the latest features and changes -
release- Stable release branch that mirrors the latest stable tag (currently v0.2.0)
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- @modelcontextprotocol/sdk - MCP SDK for protocol implementation
- keysender - Windows-only UI automation library
- clipboardy - Clipboard handling
- sharp - Image processing
- uuid - UUID generation
- 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
See CONTRIBUTING.md
This project is licensed under the MIT License - see the LICENSE file for details.
