DOCSEARCHbyAlgolia
Submit Docs

MCPControl: Windows Control Server for Model Context Protocol

repository·main·Indexed 43 days ago

https://github.com/claude-did-this/mcpcontrol

A Windows-only server for the Model Context Protocol (MCP) that allows AI models to programmatically control mouse, keyboard, window management, and screen capture. Version 0.2.0 supports multiple automation providers including keysender, powershell, and AutoHotkey v2, and offers Server-Sent Events (SSE) transport for network access.

Tokens
12.8K
Snippets
31
Records
54
Agent score
49%

What's inside MCPControl

  1. AutoHotkey Provider Capabilities

    main

    The AutoHotkey provider supports the following automation features:

    • Keyboard Automation: Typing text, pressing individual keys or combinations, and hold/release operations.
    • Mouse Automation: Moving to positions, clicking (single/double), scrolling, dragging, and retrieving cursor position.
    • Screen Automation: Getting screen size, capturing screenshots, retrieving pixel colors, and window management (focus, resize, reposition, and active window info).
    • Clipboard Automation: Setting/getting content, checking for text presence, and clearing the clipboard.

  2. Available Automation Providers in MCPControl

    main

    MCPControl uses automation providers to interact with the system. Currently, the primary provider is the Keysender Provider.

    Keysender Provider (Default)

    This provider utilizes the keysender library. It is the most comprehensive option, supporting:

    • Keyboard operations
    • Mouse operations
    • Screen operations
    • Clipboard operations

  3. How the AutoHotkey Provider works

    main

    The AutoHotkey provider operates by executing AutoHotkey v2 scripts for every individual operation.

    The execution lifecycle is as follows:

    1. A temporary .ahk script file is created for the operation.
    2. The script is executed via AutoHotkey.exe.
    3. Results are captured through script output or temporary files.
    4. Temporary files are cleaned up after execution.

    Performance Note: Because every operation involves file creation and script execution, there is higher overhead compared to native implementations. For high-frequency operations, consider batching or using a different provider.

    Known Limitations:

    • Screenshot functionality is basic and relies on Windows built-in tools (e.g., Paint, Snipping Tool).
    • Some operations may experience timing issues due to the script execution model.
    • Requires AutoHotkey v2 syntax; v1 is not compatible.

  4. Configure SSE Keep-alive and Reconnection

    main

    To ensure stable connections through proxies and handle network interruptions:

    • Keep-alive: The server must send a comment ping (":\n\n") every 25 seconds to prevent proxy idle-timeouts.
    • Reconnection: Clients use the retry:<ms> directive. You can emit retry: 3000 at the start of the stream to suggest a 3-second back-off.
    • Message Replay: When a client reconnects with a Last-Event-ID header, the server should replay missed messages from an in-memory ring buffer (default depth is 100 events).

  5. MCPControl Capabilities Overview

    main

    MCPControl provides programmatic control over Windows system operations through the following functional areas:

    • Window Management: List windows, get active window info, focus, resize, and reposition windows.
    • Mouse Control: Precision movement, click and drag operations, scrolling, and position tracking.
    • Keyboard Control: Text input, key combinations, individual key press/release, and holding keys.
    • Screen Operations: High-quality screenshots, screen size detection, and active window capture.
    • Clipboard Operations: Managing clipboard content.

  6. Select an Automation Provider via Environment Variable

    main

    To switch between available automation providers, set the AUTOMATION_PROVIDER environment variable before starting the server. By default, MCPControl uses the keysender provider.

    # Use the Keysender provider (default)
AUTOMATION_PROVIDER=keysender node build/index.js

  7. Install MCPControl on Windows

    main

    MCPControl requires specific build tools and runtimes to handle native Windows automation. Follow these steps to set up your environment:

    1. Install Build Tools: Run PowerShell as Administrator to install Visual Studio Build Tools with the VC++ workload.
    2. Install Python: Required for node-gyp.
    3. Install Node.js: Install the latest LTS version.
    4. Install the Package: Install the global npm package.

    Note: This project is currently Windows only.

    # 1. Install Build Tools (Run as Administrator)
winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

# 2. Install Python
winget install Python.Python.3.12

# 3. Install Node.js
winget install OpenJS.NodeJS

# 4. Install MCPControl
npm install -g mcp-control

  9. Configure the AutoHotkey Provider

    main

    You can configure the AutoHotkey provider via code or environment variables.

    Via Code

    As the primary provider:

    const provider = createAutomationProvider({ provider: 'autohotkey' });

    In modular configuration (specifying specific interfaces):

    const provider = createAutomationProvider({
  providers: {
    keyboard: 'autohotkey',
    mouse: 'autohotkey',
    screen: 'autohotkey',
    clipboard: 'autohotkey',
  },
});

    Via Environment Variables

    Set the global provider:

    export AUTOMATION_PROVIDER=autohotkey

    Configure the AutoHotkey executable path (optional):

    export AUTOHOTKEY_PATH="C:\\Program Files\\AutoHotkey\\v2\\AutoHotkey.exe"

    Modular configuration via environment variables:

    export AUTOMATION_KEYBOARD_PROVIDER=autohotkey
export AUTOMATION_MOUSE_PROVIDER=autohotkey
export AUTOMATION_SCREEN_PROVIDER=autohotkey
export AUTOMATION_CLIPBOARD_PROVIDER=autohotkey
    const provider = createAutomationProvider({
  providers: {
    keyboard: 'autohotkey',
    mouse: 'autohotkey',
    screen: 'autohotkey',
    clipboard: 'autohotkey',
  },
});

  10. Security Best Practices for SSE

    main

    When implementing SSE in MCPControl, consider the following security measures:

    1. CORS: Mirror your existing REST settings; do not use Access-Control-Allow-Origin: * in production.
    2. Token Handling: Prefer the Authorization: Bearer <token> header over query parameters to prevent token leakage in server logs/referrers.
    3. DoS Protection: Limit the number of concurrent SSE connections using an environment variable like MAX_SSE_CLIENTS=100. Shed the oldest connections if the limit is exceeded.
    4. Permission Model: Always enforce the existing MCP permission model before emitting sensitive data (like clipboard or mouse movements) via SSE events.

  11. Install the AutoHotkey Provider

    main

    The AutoHotkey provider implements MCPControl automation interfaces using AutoHotkey v2.

    Prerequisites:

    • Operating System: Windows (AutoHotkey is Windows-only).
    • AutoHotkey Version: v2.0 or later must be installed.
    • System PATH: AutoHotkey.exe must be available in your system PATH.

    Installation Steps:

    1. Download AutoHotkey from https://www.autohotkey.com/.
    2. Ensure you install version 2.0 or later.

  12. Implement SSE Transport in MCPControl

    main

    To add Server-Sent Events (SSE) support to MCPControl, follow this upgrade checklist:

    1. Update Types: Add SSE to the TransportType enum in src/types/transport.ts.
    2. Create Transport: Implement src/transports/sseTransport.ts extending the base Transport class.
    3. Register Route: In src/server.ts, register the /mcp/sse route using the new SseTransport.
    4. Handle Events: Implement heartbeat (ping) and Last-Event-ID tracking for message replay.
    5. Client Support: Provide documentation for client-side polyfills (e.g., eventsource npm package).
    6. Testing: Add unit tests in test/sse.spec.ts using Vitest.
    7. Documentation: Update README badges and project documentation.
     import { HttpTransport } from './transports/httpTransport';
+import { SseTransport } from './transports/sseTransport';
 
 const app = express();
 const httpTransport = new HttpTransport(app);
+const sseTransport  = new SseTransport(app);