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.

[remote-pc-mcp demo: an agent calling system_info, running a background job polled by PID, and taking a screenshot on a remote machine]

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

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-mcpcd remote-pc-mcpcp .env.example .env

Set a strong token in .env:

REMOTE_PC_MCP_TOKEN=your-long-random-token-here

Generate one:

# Windowspython -c "import secrets; print(secrets.token_hex(32))"
# Linux / macOSopenssl rand -hex 32

Then run the installer:

# Windowsinstall.bat
# Linuxchmod +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

# Windowsinstall.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-mcpremote-pc-mcp          # run the server in the foregroundremote-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:

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.

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
# Linuxsystemctl --user restart remote-pc-mcp

Logs and troubleshooting

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

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 journaljournalctl --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?

# Windowsinstall.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.

Development

Project layout:

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.txtpython -m pytest tests/ -v

License

MIT