What is Tpc Mcpv2

tpc-mcpv2 is a Total PC Control MCP server that allows programmatic control over your screen, mouse, and keyboard using nut.js. It is designed to provide a comprehensive interface for automating desktop interactions.

Use cases

Use cases for tpc-mcpv2 include automated testing of software applications, creating bots for repetitive tasks, enhancing accessibility for users with disabilities, and developing tools for remote desktop management.

How to use

To use tpc-mcpv2, clone the repository, install the necessary dependencies including cmake-js and libnut, and build the project. After setup, configure your application to interact with the MCP server as per the guidelines provided in the README.

Key features

Key features of tpc-mcpv2 include screen capture, mouse control (movement, clicks, scrolling), keyboard input (text typing and shortcuts), window management (finding and manipulating application windows), and clipboard access (copying and pasting text).

Where to use

tpc-mcpv2 can be used in various fields such as automation testing, desktop application development, and any scenario requiring programmatic control of user interface elements on a computer.

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.