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.

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:

git clone https://github.com/Cheffromspace/MCPControl.git
cd MCPControl

2. Build the project (this will handle libnut-core and all dependencies):

# Install dependencies
npm install

# Build everything including libnut-core
npm run build:all

For manual building, you can still follow these steps:

# 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:

npm test

Generate coverage report:

npm run test:coverage

MCP Server Configuration

To use this project with Claude, add the following configuration to your MCP servers:

{
  "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 - MCP SDK for protocol implementation
• @nut-tree/libnut - Core native UI automation library
• clipboardy - Cross-platform clipboard handling
• express - Web server framework
• jimp & 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

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

• NutJS Documentation
• NutJS GitHub Repository
• Model Context Protocol Documentation