Remote PC MCP Gateway (ChatGPT & Google Gemini)

English | 简体中文文档 (README.zh-CN.md)

Turn your Windows 10/11 PC into a secure, OAuth 2.1 authenticated Model Context Protocol (MCP) workstation that both OpenAI ChatGPT Web (https://chatgpt.com/) and Google Gemini Web (https://gemini.google.com/) can connect to simultaneously — with zero extra local admin ports, a native Windows Bilingual Control Panel + System Tray, and flexible public HTTPS ingress (30-second Serverless Cloudflare Quick/Named Tunnel or 1-Click Non-Destructive Linux VPS with zero-domain sslip.io Auto-HTTPS).

Key Highlights

• Dual-Client Concurrent Access (ChatGPT + Google Gemini): Connect both ChatGPT Web and Google Gemini Web to the exact same HTTPS MCP URL at the same time. Full OAuth 2.1 + PKCE (S256) + Dynamic Client Registration (/oauth/register) + MCP tool safety annotations (readOnlyHint / destructiveHint) work out of the box with zero manual Client IDs or Client Secrets.

• Three Flexible Public HTTPS Ingress Options (Switchable Anytime):

  • Mode A1 — Serverless Cloudflare Quick Tunnel (Zero Account / Ready in 30s): Spawns cloudflared locally, captures your dynamic https://*.trycloudflare.com origin, aligns OAUTH_ISSUER, and auto-detects 198.18.0.0/15 Clash/Mihomo/Sing-box TUN Fake-IP environments to switch to QUIC + Cloudflare Anycast Edge IPs seamlessly (eliminating Error 1033).

  • Mode A2 — Serverless Cloudflare Named Tunnel (Zero VPS / Permanent Domain): Paste your Cloudflare hostname and Tunnel Token in Step 1 of the GUI for a permanent HTTPS URL without renting a VPS.

  • Mode B — 1-Click Non-Destructive Linux VPS (Ubuntu/Debian): Automated provisioning (deploy/deploy-to-vps.ps1 + deploy/install-vps.sh) using a dedicated /etc/caddy/conf.d/remote-pc-mcp-gateway.caddy drop-in + automatic Caddyfile backup (never overwrites pre-existing websites on your server), supporting custom domains or zero-domain free mcp.<ip>.sslip.io Let's Encrypt TLS.

• Zero-Port Native Windows Client + System Tray: Double-click Start-GUI.bat for a clean bilingual (EN / 中文) Setup Wizard, live 5-service health strip, auto-generated persistent credentials (masked by default for screen sharing), folder list management, arrow-key wraparound navigation, and a right-click System Tray (NotifyIcon) menu.

• 5-Layer Defense-in-Depth Windows Sandbox:

  • Strict allowedRoots Path Sandbox: Every fs_* (with cross-platform .. traversal normalization and fast rg --files pruning) and read-only git_* call is strictly confined to your approved workspace folders.

  • Per-Tab Shared Chrome Isolation (pageId): Reuses your existing --remote-debugging-port=9222 Chrome while patching chrome-devtools-mcp@1.5.0 so cloud sessions must target explicit pageId tabs without touching your personal tabs.

  • Native Job Object Process-Tree Supervision (WorkbenchJob.exe) & Auto-Review: PowerShell 7 commands (run_command) execute inside a Win32 Job Object (KILL_ON_JOB_CLOSE) with zero orphan child processes on timeout, and cleanly exiting commands auto-review (review_required: false).

  • Mandatory Two-Step Delete Guard Hook (Default ON): Built-in windows/ai-workbench/delete-guard.ps1 pauses destructive commands (rm -rf, Remove-Item -Recurse, git reset --hard, etc.) on the first attempt for verification, allowing a single exact resend within 10 minutes.

  • Gemini Web Image Bridge Protection & Pluggable inspect_image: Protects Google Gemini Web from stripped {} media blocks by requiring filePath on screenshots and offering an opt-in inspect_image multimodal verifier (gemini-api, openai-api, or cli-auto).

Related MCP server: local-assistant-mcp

Which Public HTTPS Ingress Mode Should You Pick?

Architecture Overview

  OpenAI ChatGPT Web ──┐
                       ├──► HTTPS + OAuth 2.1 (PKCE S256 + Dynamic Client Registration)
  Google Gemini Web  ──┘            │
        ┌───────────────────────────┴───────────────────────────┐
        ▼ Mode A: Serverless Cloudflare Tunnel                  ▼ Mode B: 1-Click Linux VPS
 [Quick *.trycloudflare.com / Named Fixed Domain]      [Ubuntu/Debian VPS: Non-Destructive Caddy conf.d]
        │ Encrypted QUIC Tunnel (TUN Fake-IP Safe)              │ Gateway (:8787) + SSH -R Tunnel
        ▼                                                       ▼
 ┌─────────────────────────────────────────────────────────────────────────────────────┐
 │                          Your Windows 10 / 11 Workstation                           │
 │  Start-GUI.bat (Native WinForms Wizard + Dashboard + System Tray · 0 Admin Ports)   │
 │   ├── Filesystem MCP Supervisor + Bearer Proxy  (fs_* / git_* · allowedRoots)       │
 │   ├── Shared Chrome MCP Gateway (1.5.0 Patched) (chrome_* · strict pageId routing)  │
 │   └── AI Workbench + Native WorkbenchJob.exe    (run_command · Win32 Job Object)    │
 └─────────────────────────────────────────────────────────────────────────────────────┘

Prerequisites (Windows 10 / 11)

Foolproof 3-Step Quick Start (Windows PC)

Step 1 — Clone & Build Locally

git clone https://github.com/dqIndieGames/remote-pc-mcp-gateway.git
cd remote-pc-mcp-gateway
npm run setup

Tip: Even if you skip npm run setup and double-click Start-GUI.bat directly, clicking Start or ⚙ Install & Build in the GUI automatically runs the setup build in the background!

Step 2 — Double-Click Start-GUI.bat

Double-click Start-GUI.bat in Explorer. On first launch, the Setup Wizard opens automatically:

1. 1. Ingress & Server:

   • 30-Second Serverless Start: Leave Serverless Cloudflare Tunnel selected (optionally fill Named Tunnel Hostname & Token below for a permanent URL); or

   • 1-Click Self-Hosted VPS: Select Self-Hosted Linux VPS Mode, fill your VPS IPv4 & SSH user, click Browse to pick your SSH key (or leave blank to auto-detect/generate ~/.ssh/id_ed25519), and leave Domain blank to auto-provision free mcp.<ip>.sslip.io HTTPS!

2. 2. Folders, Guard & Alerts: Click + Add Folder to approve workspace folders (e.g., D:\Workspace\MyWebApp). The 2-Step Delete Guard Hook is enabled by default; System Tray Alerts and inspect_image Vision Backend are opt-in.

3. 3. Check & One-Click Start:

   • Click ⚡ One-Click Initialize & Start for Cloudflare mode, or

   • Click 🚀 One-Click Deploy to VPS & Start to provision your Linux VPS, issue TLS certificates, sync generated secrets back to config/config.local.json, and bring all 5 local services online!

Step 3 — Copy Your Masked Credentials from the Dashboard

Once the status pill turns green (● Running · Public HTTPS Ready) and all 5 service cards are green, click Copy MCP URL and Copy Approval Key.

Visual Guide 1: Connecting Google Gemini Web (gemini.google.com)

1. Open Connected Apps: Visit https://gemini.google.com/ on desktop → click Settings (bottom-left) → Connected Apps (or open https://gemini.google.com/devmode directly).

2. Click + Custom: Under Custom apps, click the blue + Custom (Add a custom app) button.

3. Paste MCP Server URL (Leave Client ID Blank): Paste your full MCP Server URL (https://<your-tunnel-or-domain>/<secret>/mcp) and click Next. Leave manual OAuth Client ID and Client Secret blank — Gemini automatically uses OAuth 2.1 Dynamic Client Registration!

4. Approve with Owner Approval Key: On your gateway's OAuth 2.1 consent card, paste your Owner Approval Key and click Approve & Connect Google Gemini:

5. Critical Step 5 — Switch Composer Mode from Chat to Task: Back in the Gemini chat box, switch the bottom-right mode selector from Chat to Task!

   • Why this matters: Gemini Web's default Chat mode does not load custom MCP tools. Once switched to Task, type @ (or ask directly) to read/edit local files, run PowerShell 7 tests, or automate Chrome!

Visual Guide 2: Connecting OpenAI ChatGPT Web (chatgpt.com)

1. Enable Developer Mode: Open https://chatgpt.com/ (Plus, Pro, Team, Enterprise, or Edu) → Settings → Connectors → Advanced → toggle Developer Mode ON.

2. Click + Create Connector: Return to Connectors and click the blue Create (Add custom MCP server) button.

3. Fill MCP URL & Select OAuth:

   • Name: My Windows PC

   • MCP Server URL: Paste the full https://.../<secret>/mcp URL from your Windows Control Panel

   • Authentication: Select OAuth

4. Approve with Owner Approval Key: Click Create, then paste your Owner Approval Key on the gateway consent page.

5. Enable in Any Chat: In a new conversation, click + (bottom-left of the composer) to enable My Windows PC — works concurrently alongside Google Gemini!

Mode B: CLI One-Click Linux VPS Deployment & Management

Prefer deploying onto a fresh or existing Ubuntu/Debian VPS directly from PowerShell?

pwsh -File .\deploy\deploy-to-vps.ps1 `
  -VpsHost 203.0.113.10 `
  -VpsUser root `
  -AllowedRoot "D:\Workspace\MyWebApp"

• Smart SSH Key Auto-Detection & Provisioning: Automatically uses -SshKeyPath or ~/.ssh/id_ed25519 (or generates an ED25519 keypair with hardened Windows icacls ACLs if none exists) and connects seamlessly via standard OpenSSH (StrictHostKeyChecking=accept-new).

• 100% Non-Destructive Caddy Integration: Backs up any existing /etc/caddy/Caddyfile and mounts a dedicated drop-in /etc/caddy/conf.d/remote-pc-mcp-gateway.caddy so pre-existing websites on your VPS remain completely untouched.

• Built-In Remote Server Helpers (run on your VPS via SSH):

  • Check gateway & TLS health: sudo mcp-gateway-status

  • Cleanly uninstall gateway while keeping existing Caddy sites intact: sudo mcp-gateway-uninstall

Shared Chrome Tab Mover Extension (Optional)

To allow chrome_move_pages_to_new_window to move AI-created test tabs into an unfocused background Chrome window without stealing focus:

1. Open chrome://extensions in your --remote-debugging-port=9222 Chrome.

2. Enable Developer mode → click Load unpacked → select windows/chrome-mcp/chrome-tab-mover-extension.

Troubleshooting & FAQ

Automated Tests & Secret Scanning

# Run OAuth 2.1 dual-platform, tool annotations, Fake-IP tunnel, Workbench & VPS dry-run unit tests
npm test

# Scan the entire repository for leaked IPs, private keys, emails, tokens, or personal paths (0 hits)
npm run scan:secrets

License

Released under the MIT License.