device-controller-mcp

An MCP (Model Context Protocol) server that lets Claude Desktop and Claude Code control your PC — take screenshots, click, type, manage windows, and more.

Features

• Two scope modes — lock every action to a single app window (--app), or grant full-desktop access (--full).

• Cross-platform — macOS and Windows, with a clean platform abstraction layer.

• Screenshot capture (full screen or single window) returned as base64 PNG.

• Mouse & keyboard — clicks, typing, key combos, scrolling.

• Window management — list, focus, resize, minimize, maximize.

• Clipboard read / write.

• Shell commands — launch apps, run commands, check running processes.

Requirements

• Python 3.10+

• macOS or Windows

Installation

git clone https://github.com/geojakes/device-controller-mcp.git
cd device-controller-mcp
pip install -e .

Platform extras

macOS — install pyobjc for accurate window bounds (optional but recommended):

pip install pyobjc-framework-Quartz pyobjc-framework-AppKit

Windows — pywin32 is required:

pip install pywin32

Usage

Scoped to a single app

pc-control-mcp --app "Google Chrome"

All screenshots, clicks, and coordinates will be relative to Chrome's window. The server auto-focuses Chrome before every action.

Full desktop

pc-control-mcp --full

Screenshots capture the whole screen and coordinates are screen-absolute.

Registering with Claude Desktop

Add an entry to your claude_desktop_config.json.

Config file location:

Full-desktop mode

{
  "mcpServers": {
    "pc-control": {
      "command": "pc-control-mcp",
      "args": ["--full"]
    }
  }
}

Scoped to one app

{
  "mcpServers": {
    "pc-control-chrome": {
      "command": "pc-control-mcp",
      "args": ["--app", "Google Chrome"]
    }
  }
}

Tip: If you installed inside a virtualenv, use the full path to the executable, e.g. "/path/to/venv/bin/pc-control-mcp".

Registering with Claude Code

claude mcp add pc-control -- pc-control-mcp --full

Or scoped:

claude mcp add pc-control-chrome -- pc-control-mcp --app "Google Chrome"

Tools reference

macOS permissions

On macOS you need to grant Accessibility access to your terminal app (or to Claude Desktop) in System Settings > Privacy & Security > Accessibility. This is required for pyautogui to control the mouse and keyboard.

Project structure

device-controller-mcp/
├── pyproject.toml
├── requirements.txt
├── README.md
└── src/
    └── pc_control_mcp/
        ├── __init__.py
        ├── __main__.py            # CLI entry point (argparse)
        ├── server.py              # FastMCP server factory
        ├── scope.py               # Scope manager (coord translation + auto-focus)
        ├── platform_layer/
        │   ├── __init__.py        # Platform detection factory
        │   ├── base.py            # Abstract base class + WindowInfo
        │   ├── macos.py           # macOS: Quartz + AppleScript
        │   └── windows.py        # Windows: pywin32
        └── tools/
            ├── __init__.py
            ├── screenshot.py      # Screen / window capture
            ├── input_control.py   # Mouse & keyboard
            ├── window_mgmt.py     # Window management
            ├── clipboard.py       # Clipboard read/write
            └── shell.py           # Shell commands & app launcher

License

MIT