Open Remote MCP

Open Remote MCP is a self-hosted, open-source control plane for securely connecting remote MCP clients to tools running on your own computers.

v0.2.0 adds OAuth authorization, browser-based device pairing, SQLite persistence, per-device tool policy, a protected visual dashboard, and persistent audit logs.

What it does

ChatGPT / Claude / Cursor / any compatible MCP client
                    |
             HTTPS + OAuth
                    v
          Open Remote MCP relay
          |        |        |
        OAuth    SQLite   Dashboard
                    |
             outbound WSS
                    v
              device agent
                    |
        scoped files / optional shell

The local device initiates the connection, so the relay never needs an inbound port on your laptop or workstation.

Related MCP server: remote-desktop-commander

Highlights

• Streamable HTTP MCP endpoint at /mcp.

• OAuth discovery with Protected Resource Metadata and Authorization Server Metadata.

• Dynamic Client Registration.

• Authorization Code flow with PKCE S256.

• Refresh tokens and advertised offline_access support.

• OAuth Device Authorization flow for agent pairing.

• Device-specific credentials; revoke from the dashboard.

• SQLite persistence for registrations, token hashes, device state, policies, and audit events.

• Two-layer permission model: server policy can narrow tools; the agent remains the final local authority.

• Realpath-based file root enforcement, including symlink escape protection.

• Shell disabled by default.

• React/Vite web control plane.

• Docker deployment files and CI.

Quick start

Requirements

• Node.js 22.5+

• npm

git clone https://github.com/Jennifer9911/open-remote-mcp.git
cd open-remote-mcp
npm install
npm run typecheck
npm run test
npm run build

Start the relay

PUBLIC_BASE_URL=http://localhost:8787 \
ADMIN_PASSWORD='choose-a-strong-password' \
SESSION_SECRET='choose-a-long-random-secret' \
npm start

The production server also serves the built web dashboard at http://localhost:8787.

Start an agent

On the machine you want the MCP client to reach:

REMOTE_MCP_SERVER=ws://localhost:8787/agent \
ALLOWED_ROOTS="$HOME/projects" \
npm run agent

On first launch the agent prints a one-time code and verification URL. Open the URL, enter the owner password, approve the device, and return to the terminal. The device credential is then saved locally with restricted file permissions.

To expose shell execution intentionally:

ALLOW_SHELL=true npm run agent

Warning: shell access has the authority of the OS account running the agent. ALLOWED_ROOTS constrains the built-in file tools, not arbitrary shell commands.

Visual control plane

The dashboard provides:

• live online/offline/revoked device state;

• local capability and root visibility;

• per-device server tool policy;

• immediate device revocation;

• persisted execution audit trail;

• security posture and connection instructions.

MCP tools

v0.2 currently exposes:

• list_devices

• ping_device

• list_directory

• read_file

• write_file

• run_command — only when enabled locally and permitted by server policy.

OAuth endpoints

• /.well-known/oauth-protected-resource

• /.well-known/oauth-protected-resource/mcp

• /.well-known/oauth-authorization-server

• /oauth/register

• /oauth/authorize

• /oauth/token

• /oauth/device/code

Access, refresh, and device credentials are stored in SQLite only as hashes.

Docker

export ADMIN_PASSWORD='choose-a-strong-password'
export SESSION_SECRET='choose-a-long-random-secret'
export PUBLIC_BASE_URL='https://remote.example.com'
docker compose up -d --build

Put the service behind HTTPS before connecting a remote MCP client over the public internet.

ChatGPT

See docs/CHATGPT.md. ChatGPT connects to remote MCP endpoints rather than directly to local stdio servers. Product availability and write permissions depend on the ChatGPT plan/workspace and can change independently of this project.

Security model

Read SECURITY.md before exposing the relay publicly. The key design rule is: cloud policy may narrow local authority, never broaden it.

Architecture

See docs/ARCHITECTURE.md.

Development

npm run dev       # relay + Vite dashboard
npm run typecheck
npm run test
npm run build

For a full local OAuth + pairing + real-agent smoke test, start a relay on port 8790 with the E2E credentials used by scripts/e2e.mjs, then run npm run test:e2e. The script exercises discovery, DCR, PKCE, refresh, device authorization, MCP execution, policy narrowing, audit persistence, and revocation.

Project layout

apps/
  server/   MCP relay, OAuth server, SQLite state, dashboard API
  agent/    outbound local device agent
  web/      visual control plane
docs/
  ARCHITECTURE.md
  CHATGPT.md

Upstream context

This is an independent implementation. It was informed by the public architecture/docs of Remote Desktop Commander and by the MIT-licensed DesktopCommanderMCP project. It does not copy the proprietary hosted Remote Desktop Commander implementation. See NOTICE.md.

License

MIT