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](https://modelcontextprotocol.io)) 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](assets/demo.gif)

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](#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](#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:

```bash
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:

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

# Linux / macOS
openssl rand -hex 32
```

Then run the installer:

```bash
# 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

```bash
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

```bash
# 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:

```bash
python server.py
```

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

### Or install from PyPI

```bash
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:

```json
{
  "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:

```json
"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:

```bash
# 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?**

```bash
# 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`) —