PC Control MCP

A safety-first Model Context Protocol server for controlled computer access and development workflows. v0.3 adds deployable multi-PC fleet management: outbound Windows agents, approval-based enrollment, online/offline status, a small admin dashboard, Docker/Caddy deployment, a Windows installer build, and in-memory screenshot transfer as MCP image content.

Security warning: this project can modify files, execute allowlisted programs, and optionally control desktops on computers where those capabilities are locally enabled. Use it only on systems you own or are authorized to administer.

Architecture

ChatGPT / MCP host
        |
        | Secure MCP Tunnel or authenticated MCP ingress
        v
+----------------------------+
| PC Control Fleet Gateway   |
| MCP       127.0.0.1:8000   |
| Admin UI  127.0.0.1:8080   |
| Agent WS  127.0.0.1:8765   |
+-------------+--------------+
              |
         Caddy HTTPS/WSS
              |
       wss://fleet.../agent
        /         |        \
       v          v         v
  office PC    home PC    laptop
   outbound     outbound    outbound
    agent        agent       agent

Controlled PCs do not need inbound firewall rules or router port-forwarding. Each agent connects outbound to the central gateway and keeps its own local policy.

Related MCP server: Terminal MCP Server

What v0.3 adds

• Approval-based automatic enrollment using a short-lived shared enrollment secret

• Unique long-term device token issued after approval; only a SHA-256 digest is stored by the gateway

• Online/offline and last_seen device state

• Browser admin dashboard for approve / enable / disable

• Remote screenshot returned as MCP ImageContent without writing a remote file

• Docker gateway image and Compose + Caddy deployment

• Caddy automatic HTTPS/WSS for agents and the admin dashboard

• Windows standalone agent + Inno Setup installer build through GitHub Actions

• Windows login auto-start instead of a Windows Service, so optional GUI automation runs in the interactive user session

Safety model

High-impact capabilities remain off by default on every PC:

• file writes: PC_MCP_ENABLE_WRITES=0

• command execution: PC_MCP_ENABLE_COMMANDS=0

• GUI automation/screenshots: PC_MCP_ENABLE_GUI=0

Filesystem access is restricted to PC_MCP_ALLOWED_ROOTS. Process execution is restricted to PC_MCP_ALLOWED_COMMANDS and always uses shell=False. The gateway cannot override these local restrictions.

Quick start: central gateway

cd deploy
cp .env.example .env
# Edit domain and generate two independent random secrets.
docker compose up -d --build

Point your domain's DNS record at the gateway host and allow inbound TCP 80/443. Caddy handles public HTTPS/WSS. The Compose file exposes the MCP endpoint only on host loopback (127.0.0.1:8000) so you can put a Secure MCP Tunnel or another authenticated MCP ingress in front of it instead of publishing an unauthenticated MCP endpoint.

Admin dashboard:

https://YOUR_DOMAIN/admin/

Enter PC_MCP_ADMIN_TOKEN in the page. See docs/DEPLOY.md.

Quick start: Windows PCs

GitHub Actions builds:

• pc-control-agent.exe

• pc-control-agent-setup-<version>.exe

The installer asks for:

1. Gateway URL such as wss://fleet.example.com/agent

2. Unique device ID

3. Enrollment key

4. Allowed filesystem roots

5. Optional write / command / GUI permissions

It stores configuration under %LOCALAPPDATA%\PCControlMCP, creates a Startup shortcut for the current user, and starts the agent. The first connection appears in the gateway admin dashboard as Pending. Approve it once; the gateway then issues a unique device token and the agent deletes its local enrollment-key file.

Python install

Python 3.11+:

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e .

Commands:

pc-control-mcp                 # one PC, direct MCP
pc-control-agent               # controlled PC outbound agent
pc-control-fleet-gateway       # central gateway

Fleet MCP tools

Discovery/status:

• list_devices

• pending_enrollments

• device_capabilities

• device_system_info

Files/development:

• device_list_directory

• device_read_text_file

• device_write_text_file

• device_replace_text

• device_make_directory

• device_run_command

• device_launch_program

• device_list_processes

Optional GUI:

• device_capture_screenshot — returns MCP image content directly

• device_take_screenshot — saves a PNG on the remote PC

• device_mouse_move

• device_mouse_click

• device_type_text

• device_press_hotkey

• device_open_url

Documentation

• docs/FLEET.md — enrollment and fleet operation

• docs/DEPLOY.md — Docker, DNS, TLS, admin dashboard, ChatGPT ingress

• SECURITY.md — threat model and hardening

License

MIT.