MCPControl
Project Status: De-prioritized. This project was created as an experiment, but Windows automation isn't something I'm looking to get deep into. I will review and merge PRs but will not be adding features soon. May revisit in the future. Looking for a maintainer.
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
- Install Node.js (if not already installed)
# Visit https://nodejs.org and download the latest LTS version
- Configure MCP settings in your Claude client:
{
"mcpServers": {
"MCPControl": {
"command": "npx",
"args": [
"--no-cache",
"-y",
"mcp-control"
]
}
}
}
- Restart your client and MCPControl will appear in your MCP menu!
🚀 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
🛠️ 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.1.22)
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
Note: As this project is currently in a maintenance-only mode, we're primarily focusing on bug fixes. However, fully implemented and well-tested features will be considered for merging. Looking for maintainers to help keep the project active.
⚖️ License
This project is licensed under the MIT License - see the LICENSE file for details.
📖 References