tpc-mcpv2

Total PC Control

An MCP (Model Context Protocol) server that provides control over your screen, mouse, and keyboard using nut.js.

⚠️ Warning: Use with Caution

This software enables programmatic control of your mouse, keyboard, and other system operations. By using this software, you acknowledge and accept that:

• Giving AI models direct control over your computer through this tool can lead to unintended consequences
• The software can control your mouse, keyboard, and other system functions
• 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

Features

• 📷 Screen Capture: Capture screenshots of your entire screen or specific regions
• 🖱️ Mouse Control: Move the mouse cursor, click, double-click, and scroll
• ⌨️ Keyboard Input: Type text and press keyboard shortcuts
• 🪟 Window Management: Find, focus, and manipulate application windows
• 📋 Clipboard Access: Copy and paste text

Prerequisites

• Node.js 16 or higher
• npm or yarn
• cmake-js (for building native dependencies)

Installation

1. Clone the repository:

git clone https://github.com/jasondsmith72/total-pc-control.git
cd total-pc-control

2. Install cmake-js globally (required for building native dependencies):

npm install -g cmake-js

3. Install the libnut core library (required for nut.js):

git clone https://github.com/nut-tree/libnut.git libnut-core
cd libnut-core
npm install
cmake-js rebuild
cd ..

4. Install dependencies and build the project:

npm install
npm run build

Using with Claude for Desktop

1. Edit your Claude for Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the following to your configuration:

{
  "mcpServers": {
    "total-pc-control": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/total-pc-control/build/index.js"
      ]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with the actual path to where you cloned the repository.

3. Restart Claude for Desktop

4. Look for the hammer icon in the Claude interface to indicate available tools.

Available Tools

Screen Capture

• capture_screen: Capture the entire screen as an image. Supports format (png/jpeg) and quality (jpeg only) parameters.
• capture_region: Capture a specific region of the screen. Requires left, top, width, height. Supports format and quality.
• get_screen_size: Get the dimensions (width and height) of the screen.

Mouse Control

• move_mouse: Move the mouse cursor to a specific x, y position.
• get_mouse_position: Get the current x, y position of the mouse cursor.
• click_mouse: Click the mouse at the current position. Optional button (left, middle, right).
• click_at: Click the mouse at a specific x, y position. Optional button.
• double_click: Double-click the mouse at the current position.
• double_click_at: Double-click the mouse at a specific x, y position.
• scroll_mouse: Scroll the mouse wheel. Requires direction (up/down). Optional amount.
• drag_mouse: Drag the mouse from the current position to a target x, y position.
• drag_mouse_from_to: Drag the mouse from a startX, startY position to an endX, endY position.

Keyboard Input

• type_text: Type text at the current cursor position. Requires text.
• type_text_with_delay: Type text with a delay between keystrokes. Requires text. Optional delayMs.
• press_key: Press a specific keyboard key. Requires key.
• press_key_shortcut: Press a keyboard shortcut (combination of keys). Requires keys array.
• hold_key: Hold down a keyboard key. Requires key.
• release_key: Release a held keyboard key. Requires key.

Clipboard Operations

• get_clipboard_text: Get text from the clipboard.
• set_clipboard_text: Set text to the clipboard. Requires text.
• copy_selected_text: Copy selected text to clipboard and return it (uses Ctrl+C/Cmd+C).
• paste_text: Paste text at current cursor position (uses Ctrl+V/Cmd+V). Requires text.
• get_clipboard_image: Get image from the clipboard (if available) as base64 data.

UI Automation Tools (Windows Only)

These tools use Windows UI Automation via PowerShell to interact with UI elements.

• get_ui_element_info: Finds a UI element within a specified window and returns its properties (Name, AutomationId, ClassName, ControlType, BoundingRectangle, IsEnabled, IsOffscreen, Value, Children).
  • Requires windowTitle (can be partial match).
  • Requires at least one of elementName, automationId, or className to find a specific element.
  • If no element identifier is provided, it lists the direct children of the window.
• invoke_ui_element_action: Performs an action on a specified UI element.
  • Requires windowTitle.
  • Requires action (Click, SetValue, or Focus).
  • Requires at least one of elementName, automationId, or className.
  • Requires valueToSet (string) if action is SetValue.

Development

To run the server in development mode:

npm run dev

To run tests:

npm test

License

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