Metadata-Version: 2.4
Name: remote-pc-mcp
Version: 0.5.0
Summary: Expose any PC's capabilities - shell, filesystem, background processes, system stats, screenshots, UI control, and file transfer - to any MCP client over streamable HTTP.
Author: Raghib Murt
License: MIT License
        
        Copyright (c) 2026 Raghib Murt
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/raghibrm/remote-pc-mcp
Project-URL: Repository, https://github.com/raghibrm/remote-pc-mcp
Project-URL: Changelog, https://github.com/raghibrm/remote-pc-mcp/blob/main/CHANGELOG.md
Keywords: mcp,model-context-protocol,remote-control,automation,tailscale
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.10.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: starlette>=0.40.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pillow>=10.0.0
Dynamic: license-file

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

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 |
| `kill_process` | Terminate a process by PID |
| `download_file` | Download a URL directly to this machine |
| `take_screenshot` | Capture the primary display — returns base64-encoded PNG |
| `click` | Click at screen coordinates `(x, y)` — left / right / middle, single or multi-click |
| `move_mouse` | Move cursor to `(x, y)`, 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 |

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`) — 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?**

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

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

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

## License

MIT

<!-- mcp-name: io.github.raghibrm/remote-pc-mcp -->
