📌Overview

Purpose: MCPControl serves as a cross-platform control server for the Model Context Protocol (MCP), enabling programmatic control over system operations such as mouse and keyboard input, window management, and screen capture.

Overview: Built on the nut.js library, MCPControl is designed to facilitate automation and interaction with user interfaces across different operating systems, including Windows, Linux, and macOS. Although currently in pre-release phase, ongoing development aims to enhance stability and broaden compatibility.

Key Features:

Window Management: Enables comprehensive management of windows, including listing, focusing, resizing, and repositioning to enhance user navigation and interaction with the graphical interface.
Mouse Control: Provides functionalities for mouse movement, clicking, scrolling, and dragging, allowing precise control over cursor actions within applications.
Keyboard Control: Supports text input, key combinations, and other keyboard operations, facilitating advanced automation of user interactions.
Screen Operations: Allows for screen capture and detection of the active window, enabling visual automation tasks.
Clipboard Integration: Facilitates interaction with the clipboard, including reading and writing content to enhance data manipulation capabilities.

MCPControl

Windows control server for the Model Context Protocol, providing programmatic control over system operations including mouse, keyboard, window management, and screen capture functionality.

This project was initially developed as an experiment to see if Claude could play some video games. After initial success and community interest, development has resumed toward a stable release.

Note: This project currently supports Windows only.

⚠️ 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 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.
Use this tool only in controlled environments with appropriate safety measures.

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

Usage

Simply configure your Claude MCP settings to use MCPControl as shown below. No installation needed!

Building From Source

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 requiring these build tools.

MCP Server Configuration

Install Node.js using the official Windows installer, which includes necessary build tools
Install additional required tools:

npm install -g node-gyp
npm install -g cmake-js

Add the following configuration to your MCP settings:

{
  "mcpServers": {
    "MCPControl": {
      "command": "npx",
      "args": [
        "--no-cache",
        "-y",
        "mcp-control"
      ]
    }
  }
}

After configuring your MCP settings, restart your client 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
keysender - Windows-only UI automation library
clipboardy - Clipboard handling
sharp - Image processing
uuid - UUID generation

Testing

The project currently includes unit tests for core functionality. Planned future tests include:

Integration tests for cross-module functionality
Performance testing
Error handling validation

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.

Contributing

See CONTRIBUTING.md

License

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

References

Model Context Protocol Documentation