Musu Remote MCP for Windows

A Windows-native remote development MCP server for a trusted personal workstation. It runs on Node.js and PowerShell 7 without Docker, exposes OAuth 2.1 over Streamable HTTP, and protects mutations with byte-exact checkpoints and durable jobs.

This repository is the Windows edition of remote_dev_mcp. It retains attribution to kstost/cokacremote.

Capabilities

• Native Windows 11 execution with Node.js 22.13+

• PowerShell 7 command and script execution with UTF-8 output preservation

• 23 MCP tools, OAuth CIMD+DCR/PKCE/refresh/revocation, client-owned jobs

• Target checkpoints for direct edits and full checkpoints before shell/script/patch jobs

• Content-addressed backups, bounded queues, idempotency keys, restart recovery

• Windows path, drive-letter, junction/symlink, hard-link, and process-tree handling

• Kill-on-close Windows Job Object containment for every command tree

• Authenticated Prometheus metrics and Windows Application Event Log lifecycle events

• Verified foreground operation and beta Windows service operation through pinned WinSW

• Cloudflare named tunnel guidance for a fixed HTTPS endpoint

Related MCP server: Secure Host MCP

Security boundary

This server intentionally executes arbitrary commands. In native mode, those commands receive every permission of the Windows account running the MCP service. Docker mount and capability isolation are absent. Configure only the directories that the service account may edit, grant that account the minimum NTFS access it needs, and connect only trusted MCP clients.

The recommended service installation separates the OAuth gateway and execution worker into NT SERVICE\MusuRemoteMcpGateway and NT SERVICE\MusuRemoteMcpWorker. Explicit deny ACLs keep the gateway out of editable roots/backups and the worker out of OAuth state. Requests cross loopback with a short-lived HMAC assertion bound to client ID, nonce, timestamp, and body. The worker still executes arbitrary code with all rights granted to its dedicated identity, so this remains a trusted single-operator system rather than a hostile-code sandbox. Read SECURITY.md.

Requirements

• 64-bit Windows 11 or Windows Server 2022+

• Node.js 22.13 or newer, installed system-wide for service mode

• PowerShell 7 or newer, installed system-wide for service mode

• Git available on PATH for patch operations

• Administrator access only when installing the Windows service or Cloudflare service

• A fixed HTTPS URL for ChatGPT; Cloudflare named tunnel is the documented path

Docker Desktop is not required.

Documentation index

• Code and document index

• Windows architecture

• Operations and incident response

• Code audit

• Optimization and maturity review

• Windows acceptance evidence

• Real ChatGPT compatibility evidence

• MUSU workspace switchover

Install and run in the foreground

git clone https://github.com/yellowhama/musu_remote_mcp_win.git
Set-Location musu_remote_mcp_win

pwsh -File .\windows\Install.ps1 `
  -EditableRoot 'F:\workspace\musu-active\musu-bee','F:\workspace\musu-active\llm-wiki' `
  -DefaultCwd 'F:\workspace\musu-active\musu-bee' `
  -StateRoot 'F:\musu-remote-mcp-data\state' `
  -BackupRoot 'F:\musu-remote-mcp-data\backups' `
  -PublicUrl 'https://mcp.example.com'

pwsh -File .\windows\Start-Local.ps1

The installer uses npm ci, builds the vendored TypeScript server, creates config\windows.json, initializes separate OAuth approval and metrics keys, and restricts the state directory ACL. It never prints either key value.

The approval key full path is the configured stateRoot plus approval-key.txt, for example:

F:\musu-remote-mcp-data\state\approval-key.txt

The metrics-only key is stored beside it at metrics-key.txt. It can read /metrics and cannot authenticate to /mcp.

Install as a Windows service (beta)

Open PowerShell 7 as Administrator and run the split-service installer:

pwsh -File .\windows\Install-SplitService.ps1 `
  -EditableRoot 'F:\workspace\musu-active\musu-bee','F:\workspace\musu-active\llm-wiki' `
  -PublicUrl 'https://mcp.example.com' `
  -StateRoot 'F:\musu-remote-mcp-data\state' `
  -BackupRoot 'F:\musu-remote-mcp-data\backups'

Service mode downloads WinSW 2.12.0 and verifies this pinned SHA-256 before use:

05B82D46AD331CC16BDC00DE5C6332C1EF818DF8CEEFCD49C726553209B3A0DA

The gateway alone can read the approval key and OAuth SQLite state. The worker alone can modify editable roots, checkpoints, and durable job state. Both can read a separate broker key directory; neither receives the other service's data permissions. The older Install.ps1 -Service combined mode remains for migration only.

To remove only the service registration while retaining source, state, and backups:

pwsh -File .\windows\Uninstall-SplitService.ps1

Cloudflare named tunnel

ChatGPT connects to a remote MCP endpoint, so local execution still needs a secure remote tunnel. Install cloudflared, create a named tunnel and fixed hostname, then point its ingress at http://127.0.0.1:39391.

Use windows/cloudflared-config.yml.example as the starting configuration. Cloudflare documents native Windows service installation with cloudflared.exe service install. Set the same fixed HTTPS hostname as publicUrl in config\windows.json.

Quick Tunnels are intended only for testing. Their hostname changes when restarted; they have no uptime guarantee, cap concurrent in-flight requests at 200, and do not support SSE. A named tunnel is required for the supported persistent configuration.

Connect ChatGPT

1. Confirm http://127.0.0.1:39391/health returns HTTP 200 locally.

2. Confirm the named tunnel routes https://your-host.example/health.

3. In ChatGPT developer mode, create a custom MCP app at https://your-host.example/mcp and choose OAuth.

4. Enter the approval key only on this server's OAuth approval page.

5. Scan tools and confirm that 23 tools are present.

6. Start with a read-only request for the repository instruction file.

The authorization-server metadata advertises Client ID Metadata Document (CIMD) support while retaining Dynamic Client Registration (DCR) for existing ChatGPT clients. CIMD documents must use a canonical HTTPS URL and a public network destination; the server pins the resolved address, rejects redirects, and bounds retrieval time and size.

The 2026-09-14 acceptance run confirmed that a real ChatGPT custom MCP app selected CIMD, completed OAuth, discovered the server and all tools, and executed a read-only tool call through the split gateway and worker. The gateway preserves modern Mcp-* protocol headers when proxying requests and responses. DCR remains enabled until a broader compatibility window shows it is unused.

Authenticated operators can scrape /metrics with the dedicated metrics key or a valid OAuth credential. The fixed-cardinality metrics cover HTTP status and latency, authentication rejection, CIMD-versus-DCR resolution, managed processes, mutation queue depth, checkpoint outcomes/bytes/duration, and workspace free space. The metrics key is route-scoped and does not grant MCP tool access.

For a measured fresh ChatGPT connection, capture a baseline, create and exercise a new app, then capture the result:

pwsh -File .\windows\Capture-ChatGPTCompatibility.ps1 -Phase Begin
# Complete OAuth, scan tools, and make at least one tool call in ChatGPT.
pwsh -File .\windows\Capture-ChatGPTCompatibility.ps1 -Phase End

On an elevated disposable VM, prepare an automatic post-boot verification and then reboot:

pwsh -File .\windows\Test-RebootPersistence.ps1 -Phase Prepare -RestartComputer
pwsh -File .\windows\Test-RebootPersistence.ps1 -Phase Status

Configuration

The installer creates the ignored file config\windows.json. The checked-in example documents every supported field.

The native runtime rejects unknown fields, non-absolute paths, missing roots, overlapping roots, comma-containing roots, unsafe public URLs, and out-of-range ports before starting. It resolves Windows 8.3 aliases and other existing path aliases to canonical paths before applying containment checks.

Mutation and recovery model

Direct file mutations snapshot exact targets before invoking the upstream tool. Shell, PowerShell, script, patch, move, copy, and remove jobs create a full checkpoint first. Job records are written durably and incomplete jobs found after restart become interrupted_unknown; they are never replayed automatically.

Snapshots are file-consistent rather than filesystem-atomic. They do not capture complete NTFS ACLs, alternate data streams, open database transactions, or every external effect of a command. Restore drills write to a new directory and never overwrite live roots.

Verification

npm ci
npm run build
npm test

Preview retention without changing files, then stop the MCP server and apply the reviewed plan:

pwsh -File .\windows\Maintain.ps1
pwsh -File .\windows\Maintain.ps1 -Apply

Retention keeps the newest manifest even when it is older than the configured window, archives terminal jobs, removes only objects unreachable from retained manifests, and records a two-phase maintenance plan before deletion. Before every direct or full checkpoint, the runtime also reserves the configured retention.minFreeBytes after accounting for the checkpoint's worst-case bytes. The installer defaults this watermark to 10 GiB.

GitHub Actions runs the same build and test flow on windows-latest with Node.js 24. The native smoke test starts the real OAuth server, checks health 200 and unauthenticated MCP 401, verifies key creation, and terminates the process tree.

See the Dockerless research, architecture, operations, and optimization and maturity review.

License

MIT. Upstream license and attribution are preserved in LICENSE, NOTICE, and vendor/.