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 OAuth gateway, execution worker, state, and backups share one service identity. An authenticated shell job can therefore read anything that identity can read, including MCP state. This is suitable for one trusted operator on a personal development PC. It is not a hostile-code sandbox or multi-tenant boundary. 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.

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-bee','F:\workspace\llm-wiki' `
  -DefaultCwd 'F:\workspace\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 the OAuth approval key, and restricts the state directory ACL. It never prints the 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

Install as a Windows service (beta)

Open PowerShell 7 as Administrator and add -Service:

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

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

05B82D46AD331CC16BDC00DE5C6332C1EF818DF8CEEFCD49C726553209B3A0DA

The service runs as NT AUTHORITY\LocalService. The installer grants that shared low-privilege identity read/execute access to the application and modify access to the configured editable, state, and backup roots. Review this choice if another local service should not share those directories.

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

pwsh -File .\windows\Uninstall-Service.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.

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.

Authenticated operators can scrape /metrics with the same bearer/OAuth credentials used for MCP. The fixed-cardinality metrics cover HTTP status and latency, authentication rejection, managed processes, mutation queue depth, checkpoint outcomes/bytes/duration, and workspace free space. 5. Scan tools and confirm that 23 tools are present. 6. Start with a read-only request for the repository instruction file.

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