remote-pc-mcp

remote-pc-mcp

Expose any PC's capabilities — shell, filesystem, background processes, system stats, screenshots, UI control, and file transfer — to any MCP client (Claude Desktop, Claude Code, Cursor, Cline, Continue, Windsurf, custom agents — anything that speaks the Model Context Protocol) over streamable HTTP.

Drop it on any machine you want to drive remotely: a home server, a desktop, a build/CI box, a media server, a workstation, a Raspberry Pi. From a separate machine, your AI agent of choice can run commands on it, manage files, launch and monitor background jobs, take screenshots, and drive the desktop UI.

The transport is the mcp SDK's streamable HTTP (stateless_http=True), so a server restart does not break already-connected clients. Each request is self-contained — there is no in-memory session to go stale.

⚠️ shell_exec runs arbitrary commands on the host as the user that started the server. The bearer token is a root-equivalent credential. See Security before exposing the server.

Tools

Tool	Description
shell_exec	Run any shell command — returns stdout, stderr, exit code
read_file	Read a file as text or base64 (binary fallback)
write_file	Write text or binary content to a file
list_directory	List files and directories, optionally recursive
system_info	OS, CPU, RAM, and GPU stats (NVIDIA GPUs via nvidia-smi; absent on non-GPU hosts)
start_process	Start a long-running command in the background — returns a PID
get_process_output	Poll stdout/stderr of a background process by PID, plus its exit code once it ends
kill_process	Terminate a process by PID
download_file	Download a URL directly to this machine
take_screenshot	Capture the whole desktop, every monitor, as an image sized for a vision model (screen coordinates)
click	Click at (x, y) in the screenshot — left / right / middle, single or multi-click
move_mouse	Move cursor to (x, y) in the screenshot, optionally animated
type_text	Type a string into the focused window
press_key	Press a single key or hotkey combo (e.g. enter, f11, ctrl+c, win+d)
scroll	Scroll the mouse wheel up or down, optionally at a specific point

Requirements

• Python 3.10+
• Windows 10/11, or Linux with systemd (for autostart)

Install

On the machine you want to control:

git clone https://github.com/raghibrm/remote-pc-mcp
cd remote-pc-mcp
cp .env.example .env

Set a strong token in .env:

REMOTE_PC_MCP_TOKEN=your-long-random-token-here

Generate one:

# Windows
python -c "import secrets; print(secrets.token_hex(32))"

# Linux / macOS
openssl rand -hex 32

Then run the installer:

# Windows
install.bat

# Linux
chmod +x install.sh
./install.sh

That's it — one command. The installer:

• installs Python dependencies
• registers the server to launch hidden on every login (Startup-folder shortcut on Windows, systemd user unit on Linux)
• starts it now
• supervises it with exponential backoff on crash (5→10→20→40→60 seconds, resets after 5 minutes of uptime)
• survives reboots — set once, runs forever

Verify it's up

curl http://localhost:8765/health
# {"status":"ok","server":"remote-pc-mcp","version":"0.5.0"}

When to rerun the installer

install.bat / install.sh are idempotent and self-healing. Rerun any time after:

• You move the repo to a different folder
• You reinstall or upgrade Python to a different path
• You rebuild the machine and want to restore autostart

For day-to-day operation you never need to think about it.

After a reboot

Autostart fires when you sign in to Windows. A reboot that sits at the lock screen will NOT start the daemon until somebody logs in. This is intentional — enabling Windows auto-logon to make reboots fully hands-off would let anyone with physical access to the machine get a logged-in desktop, which is the wrong trade-off for a remote-control tool.

If you need to bring the daemon back up after a reboot without walking to the PC, sign in remotely via Remote Desktop or Tailscale SSH. Once you're logged in, the Startup shortcut fires and the daemon starts.

Linux is different: install.sh --linger runs sudo loginctl enable-linger $USER so the systemd user unit runs across reboots without any logon. systemd's user services don't share the auto-logon security problem because they don't grant interactive desktop access — they just keep your user-scoped daemons alive.

Uninstall

# Windows
install.bat --uninstall

# Linux
./install.sh --uninstall

Removes the autostart entry and stops the running server + supervisor.

Foreground run (development)

For a one-off run with visible console output and no autostart:

python server.py

That's it — no special script. Use install.bat / install.sh for the normal supervised setup.

Or install from PyPI

pip install remote-pc-mcp
remote-pc-mcp          # run the server in the foreground
remote-pc-mcp-daemon   # supervised: restarts the server on crash

A pip install gives you the server and supervisor commands but does not register autostart. For autostart on sign-in, use the clone and install-script path above. .env, logs, and .state/ live in REMOTE_PC_MCP_HOME (default: the working directory).

Adding to your MCP client

Most MCP clients use the same JSON schema; the file just lives in different places. Example:

{
  "mcpServers": {
    "remote-pc": {
      "type": "http",
      "url": "http://YOUR_PC_IP_OR_HOSTNAME:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-long-random-token-here"
      }
    }
  }
}

Where to put it:

Client	Config file
Claude Code	.mcp.json in the project root (or ~/.claude.json for user-wide)
Claude Desktop	claude_desktop_config.json (Settings → Developer → Edit Config)
Cursor	.cursor/mcp.json
Cline / Continue / Windsurf	each has its own MCP servers panel — paste the JSON there
Custom agents	wherever your agent reads MCP server definitions

For Tailscale users, the magic-DNS hostname works in the URL:

"url": "http://your-pc.tail12345.ts.net:8765/mcp"

Restart (or reload) your client. The tools appear automatically. The "remote-pc" key is just a label — pick whatever name you want.

Security

shell_exec runs any command on the host as the user that started the server. That is intentional — it is what makes the server useful for remote-driving a PC. It also means:

• The bearer token is a root-equivalent credential. Generate a 32-byte hex token, store it only in .env (which is git-ignored), and treat it like a password.
• Never expose the server to the public internet without TLS and a reverse proxy (nginx, Caddy, Cloudflare Tunnel).
• Use Tailscale (strongly recommended): bind to your Tailscale IP (set REMOTE_PC_MCP_HOST=100.x.x.x in .env) so the listener is only reachable from devices in your tailnet.
• LAN-only deployments with REMOTE_PC_MCP_HOST=0.0.0.0 are reasonable if you trust every device on the LAN and have a strong token. Don't do this on an untrusted network.

The token is compared with secrets.compare_digest (constant-time). All error messages pass through a sanitiser that strips absolute paths, the home directory, and the token before being returned to clients.

Configuration

All env vars are optional except REMOTE_PC_MCP_TOKEN.

Var	Default	Description
REMOTE_PC_MCP_TOKEN	(required)	Bearer token clients must present
REMOTE_PC_MCP_HOST	0.0.0.0	Bind address. Set to a Tailscale IP to restrict reach
REMOTE_PC_MCP_PORT	8765	Listen port
REMOTE_PC_MCP_ALLOWED_HOSTS	(empty)	Comma-separated allowlist for DNS-rebinding protection. Empty disables it (default — wrong threat model on a tailnet)
REMOTE_PC_MCP_MAX_SHELL_TIMEOUT	600 (s)	Cap on per-call shell_exec timeout
REMOTE_PC_MCP_MAX_READ_BYTES	50 MB	read_file upper limit
REMOTE_PC_MCP_MAX_WRITE_BYTES	50 MB	write_file upper limit
REMOTE_PC_MCP_MAX_DOWNLOAD_BYTES	2 GB	download_file upper limit
REMOTE_PC_MCP_SCREEN_MAX_EDGE	1568 (px)	Longest edge of the take_screenshot image. 0 turns the limit off
REMOTE_PC_MCP_SCREEN_MAX_PIXELS	1150000	Total pixels of the take_screenshot image. 0 turns the limit off

After changing .env, restart the server so the new value takes effect:

# Windows: easiest path is just re-run the installer (idempotent)
install.bat --uninstall && install.bat

# Linux
systemctl --user restart remote-pc-mcp

Logs and troubleshooting

Two log files in the repo root, both rotated automatically:

File	What's in it	Rotation
server.log	App events + uvicorn startup/access logs	10 MB × 5
daemon.log	Supervisor events (crashes, restarts, backoff)	2 MB × 3

Server isn't responding?

# Is the listener up locally?
curl http://localhost:8765/health

# What's the supervisor seeing?
tail -f daemon.log

# Linux: full journal
journalctl --user -u remote-pc-mcp -f

# Windows: is the autostart registered?
explorer shell:startup    # look for remote-pc-mcp.lnk

MCP client says tools are missing after a server restart?

The streamable HTTP transport is designed so a restart does not brick clients, but the client still has to issue a request to notice the new server. First fix: invoke any tool from this server (e.g. ask your agent to run system_info) — the client will retry the connection. If that fails, reconnect the MCP server in your client (Claude Code: /mcp ; Cursor: refresh in MCP panel) or restart the client.

Stuck process / port already in use?

# Windows
install.bat --uninstall && install.bat

# Linux
./install.sh --uninstall && ./install.sh

UI-driving tools

take_screenshot, click, move_mouse, type_text, press_key, and scroll require an interactive desktop session:

• Windows: a user must be logged in and the screen unlocked. A service running under Session 0 cannot reach the desktop. The Startup-folder install gives you exactly this — the daemon runs in your user session.
• Linux: needs an X11 or Wayland session. For screenshots specifically, install scrot, gnome-screenshot, or ImageMagick's import — sudo apt install scrot is the easiest.

Screen coordinates

A vision model sees a screenshot shrunk to fit its image limits, and the coordinates it answers with are in that shrunken image. So take_screenshot shrinks the desktop itself, to at most REMOTE_PC_MCP_SCREEN_MAX_EDGE pixels on the long edge and REMOTE_PC_MCP_SCREEN_MAX_PIXELS in total. The defaults match the Claude API's standard image limits, so the client does not shrink it again. The result is a JPEG image plus a JSON block with the image size, the scale, the desktop's geometry, and the path of the full-resolution PNG on the host.

click, move_mouse, and scroll take (x, y) in that image's pixels. The server maps each point back to the real desktop, including monitors left of or above the primary one, which have negative desktop coordinates. Each call also returns the desktop_x, desktop_y it used. The mapping depends only on the desktop's current size, so a client can click without taking a screenshot first, as long as it uses the same image size. Set both limits to 0 for a full-resolution image, one pixel per desktop pixel. Coordinates still count from the image's top-left corner.

On Windows the server runs per-monitor DPI-aware, so the capture and the mouse use physical pixels on every monitor, whatever its scale.

Development

Project layout:

File	Purpose
server.py	The MCP server — tools, auth, transport
daemon.py	Supervisor — spawns server, restarts on crash with backoff
_logging.py	Shared logging config — one handler for app + uvicorn loggers
_screen.py	Screen space: how the screenshot is sized and how its pixels map to the desktop
install.{bat,sh}	Single entry point: default installs, --uninstall removes

Tests

A self-contained test suite under tests/ launches its own isolated server on a high port with an ephemeral token, exercises every tool, and verifies that a mid-run server restart does not lock the client out. It does not touch the production server you have running.

pip install -r requirements-dev.txt
python -m pytest tests/ -v

License

MIT