https://github.com/Cheffromspace/nutjs-windows-control
Cross-platform MCP server for OS automation
https://github.com/Cheffromspace/nutjs-windows-control
ai claude computer-control computer-vision mcp os-automation windows
Last synced: 26 days ago
JSON representation
Cross-platform MCP server for OS automation
- Host: GitHub
- URL: https://github.com/Cheffromspace/nutjs-windows-control
- Owner: Cheffromspace
- License: mit
- Created: 2024-12-03T17:40:27.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2025-03-19T02:52:32.000Z (about 1 month ago)
- Last Synced: 2025-03-20T11:47:03.316Z (about 1 month ago)
- Topics: ai, claude, computer-control, computer-vision, mcp, os-automation, windows
- Language: TypeScript
- Homepage:
- Size: 398 KB
- Stars: 14
- Watchers: 1
- Forks: 4
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - Windows Control - Windows automation MCP server providing mouse, keyboard, screen capture, clipboard, and window management capabilities using NutJS. (🤖 <a name="system-automation"></a>System Automation)
- Awesome-MCP-Servers-directory - Windows Control - Programmatic control over Windows system operations including mouse, keyboard, window management, and screen capture using nut.js (System Automation)
- awesome-mcp-servers - Windows Control - Programmatic control over Windows system operations including mouse, keyboard, window management, and screen capture using nut.js. (Community Servers)
- awesome-mcp-servers - Windows Control - MCP server for Windows OS automation (Table of Contents / System Automation)
- awesome-mcp-servers - Windows Control - MCP server for Windows OS automation (Table of Contents / System Automation)
README
# MCPControl
A cross-platform control server for the Model Context Protocol (MCP), providing programmatic control over system operations including mouse, keyboard, window management, and screen capture functionality. Built on [nut.js](https://nutjs.dev/).
I developed this project as an experiment a few months ago, wanting to see if Claude could play some video games. After seeing it work, I was impressed but set it aside. Recently, it's gained attention from the community, prompting me to resume development. While currently in pre-release state, I'm actively working toward a stable version. If you encounter any issues, please submit them through the issue tracker.
> **Note**: This project aims to support Windows, Linux, and macOS. While most testing has been performed on Windows, cross-platform compatibility contributions are welcome.
## ⚠️ 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
- **Window Management**
- List all windows
- Get active window information
- Get window titles
- Get window size and position
- Focus windows
- Resize windows
- Reposition windows
- **Mouse Control**
- Mouse movement
- Click operations
- Scroll functionality
- Drag operations
- Cursor position tracking
- **Keyboard Control**
- Text input
- Key combinations
- Key press/release operations
- Hold key functionality
- **Screen Operations**
- Screen capture
- Screen size retrieval
- Active window detection
- **Clipboard Integration**
- Get clipboard content
- Set clipboard content
- Clear clipboard
- Check clipboard state
## Installation
1. Clone the repository:
```bash
git clone https://github.com/Cheffromspace/MCPControl.git
cd MCPControl
```
2. Build the project (this will handle libnut-core and all dependencies):
```bash
# Install dependencies
npm install
# Build everything including libnut-core
npm run build:all
```
For manual building, you can still follow these steps:
```bash
# Install cmake-js globally (required for building)
npm install -g cmake-js
# Clone libnut repository directly in the project directory
git clone https://github.com/nut-tree/libnut.git libnut-core
cd libnut-core
# Install dependencies and build
npm install
cmake-js rebuild
# Return to the main project
cd ..
# Build MCPControl
npm run build
```
### Running Tests
Run all tests:
```bash
npm test
```
Generate coverage report:
```bash
npm run test:coverage
```
## MCP Server Configuration
To use this project with Claude, add the following configuration to your MCP servers:
```json
{
"mcpServers": {
"MCPControl": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": [
"[INSTALL LOCATION]\\MCPControl\\build\\index.js"
]
}
}
}
```
After configuring your MCP server, restart Claude to see the MCPControl service in the menu.
## Project Structure
- `/src`
- `/handlers` - Request handlers and tool management
- `/tools` - Core functionality implementations
- `/types` - TypeScript type definitions
- `index.ts` - Main application entry point
## Dependencies
- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - MCP SDK for protocol implementation
- [@nut-tree/libnut](https://github.com/nut-tree/libnut) - Core native UI automation library
- [clipboardy](https://www.npmjs.com/package/clipboardy) - Cross-platform clipboard handling
- [express](https://expressjs.com/) - Web server framework
- [jimp](https://www.npmjs.com/package/jimp) & [sharp](https://www.npmjs.com/package/sharp) - Image processing
## Testing
The project currently includes unit tests for core functionality. The following test areas are planned for future development:
- Integration tests for cross-module functionality
- Performance testing
- Error handling validation
## Known Limitations
- Window minimize/restore operations are currently unsupported in libnut-core
- Advanced screen information (multiple monitors, DPI settings) is limited to main display
- Some operations may require elevated permissions depending on the target application
- Cross-platform support (Linux/macOS) is untested
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## References
- [NutJS Documentation](https://nutjs.dev/)
- [NutJS GitHub Repository](https://github.com/nut-tree/nut.js)
- [Model Context Protocol Documentation](https://modelcontextprotocol.github.io/)