# Private Desktop MCP

Self-hosted multi-device [Model Context Protocol](https://modelcontextprotocol.io/) bridge for Desktop Commander using Cloudflare Workers, Durable Objects and a one-command Windows connector.

**Transport:** Streamable HTTP to ChatGPT; outgoing WebSocket from the device to the relay.

## Public npm release

```powershell
npx.cmd --yes --prefer-online --package=@juexibobi/private-desktop-mcp@latest -- private-desktop-mcp connect
```

Each release gets its own immutable npm version. **Do not overwrite a fixed `.tgz` at a stable URL**: npm caching might start an old version.

### Terminal logging (v0.3.6)

PCC now uses **TRACE logging by default**. The normal `connect` command prints MCP call IDs, sanitized/truncated command and response previews, timings, connection details, and errors. There is no need for `--trace`.

**Privacy:** TRACE can reveal sensitive file contents or command output. Redaction is best effort; avoid sharing or recording the terminal. Use `--debug` for detailed metadata without content previews, or `--safe` for compact logs. The former `--trace` flag remains supported for compatibility.

### Windows system proxy detection (v0.3.4)

PCC automatically uses the current Windows user's **effective system proxy** (WinINET), including static HTTP/Mixed proxies, Windows proxy bypass rules, and supported PAC/WPAD configurations. It uses the same detected proxy for the HTTPS device-pairing API and for the secure WebSocket relay. No manual `HTTPS_PROXY` configuration is required for normal Windows system proxy settings.

Explicit `HTTPS_PROXY`, `HTTP_PROXY` or `ALL_PROXY` settings take precedence over Windows settings; `NO_PROXY` exclusions are respected for an explicitly configured environment proxy. Supported proxy transport is HTTP/HTTPS CONNECT. SOCKS-only proxy endpoints must be exposed through an HTTP/Mixed port. The detected proxy is re-checked periodically when retrying a lost connection. If system lookup fails or times out, PCC reports a warning and tries a direct connection.

Debug mode prints **redacted parameter metadata and response size/type**, not command contents, file contents or raw tool results. Sensitive fields and inline tokens are masked, but local paths and other non-sensitive metadata may still appear, so avoid sharing debug logs publicly. The child gateway's detailed stderr/stdout is still stored at `%TEMP%\private-desktop-mcp-device.log`. Neither logging mode changes device pairing, OAuth or startup behavior.

## Current independent endpoint

```text
https://private-desktop-device-relay.ljx2043979076.workers.dev/mcp
```

Set up a remote Streamable HTTP MCP connection with Cloudflare Access OAuth. The gateway and device pairing admin page share this free workers.dev host. The old qqking.top route is a temporary fallback, not a dependency of this connector.

## Pairing devices

1. On a Windows machine with Node.js 20.18.1+ run `private-desktop-mcp connect` after installation (or the npx command above).
2. The first run prints an expiring pairing code and an Access-protected approval URL.
3. Sign into Cloudflare Access and approve the **matching code** in the admin page.
4. The device saves a locally scoped credential in the user's AppData and connects via WebSocket. Never commit or share that credential.
5. Leave the terminal open while using tools. Press **Ctrl+C** to disconnect. No startup tasks or Windows services are installed.
6. Reconnecting the same paired device needs no further approval. Revoke old devices from the admin page.

If multiple devices are online, select the intended one at the admin page. The relay must never route to an arbitrary device when the target is ambiguous.

## Running without npm publication

Install from your own checked-out repository with `npm install` then `node bin/cli.mjs connect`. To install globally from the project: `npm install -g .`.

## Cloudflare deployment

The Worker source is in `worker/index.mjs`. The infrastructure is described by `wrangler.toml`. Production has a **separate Cloudflare Access self-hosted application** protecting exactly `/mcp` and `/admin/*`, with Owner-only policy. Device pairing paths `/relay/*` remain reachable but device WebSocket access is protected by a bearer token issued only after pairing approval.

Never protect the **entire Worker** with Worker-level Access: this would prevent WebSocket connections. Never deploy the Worker without first configuring path-based Access for the MCP and admin endpoints. Use Wrangler or Cloudflare API credentials provided directly in your own secure environment.

`worker/index.mjs` currently supports the legacy qqking.top host for rollback. The free workers.dev endpoint is the canonical address.

## Releases

- CI executes syntax tests and package validation.
- Immutable versioned npm packages carry the authoritative `latest` dist-tag.
- Release workflow uses **GitHub Actions OIDC npm trusted publishing** for this repository and release.yml; no long-lived npm publish token is needed.
- GitHub Releases preserves the same immutable `.tgz` as a backup.
- Secrets, local `device.json`, `.env`, `node_modules` and existing Cloudflare Access policies are not stored in Git.

## Security

This tool has Windows filesystem and command-execution capabilities. Restrict Cloudflare Access to your own identity, approve only devices you control and never expose a naked HTTP MCP endpoint. See [SECURITY.md](SECURITY.md).