Secure Host MCP

<p align="center"> <a href="https://github.com/Razewang/secure-host-mcp/actions/workflows/ci.yml"><img src="https://github.com/Razewang/secure-host-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/Razewang/secure-host-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/Razewang/secure-host-mcp?label=Release" alt="Latest release"></a> <a href="https://www.npmjs.com/package/secure-host-mcp"><img src="https://img.shields.io/npm/v/secure-host-mcp?logo=npm" alt="npm"></a> <img src="https://img.shields.io/badge/Windows-x64-0078D4?logo=windows" alt="Windows x64"> <img src="https://img.shields.io/badge/Linux-x64-FCC624?logo=linux&logoColor=000000" alt="Linux x64"> <img src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 20+"> <img src="https://img.shields.io/badge/MCP-Streamable%20HTTP-5A45FF" alt="MCP Streamable HTTP"> <a href="https://github.com/Razewang/secure-host-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a> </p>

<p align="center"> English | <a href="README.zh-CN.md">简体中文</a> </p>

Secure Host MCP exposes a Windows or Linux host terminal to remote MCP clients through Streamable HTTP. It is intentionally powerful: the default administrator token can execute any command available to the service account, inspect or launch configured tunnels, and request privileged operations.

Download a standalone release

Download the archive for your platform from GitHub Releases:

• Windows x64: extract the ZIP and double-click secure-host-mcp.exe. On first launch the console wizard asks about public-IP and Cloudflare Tunnel access, configures the administrator token, displays the connection URLs, and starts both servers.
• Linux x64: extract the tar.gz archive and run ./secure-host-mcp launch for the same first-run initialization and startup behavior.

No separate Node.js installation is required for these archives. The Windows executable is not code-signed yet, so Microsoft Defender SmartScreen may display an unknown-publisher warning. Verify the download against SHA256SUMS.txt before running it.

# Windows PowerShell
(Get-FileHash .\secure-host-mcp-0.1.0-windows-x64.zip -Algorithm SHA256).Hash

# Linux
sha256sum -c SHA256SUMS.txt --ignore-missing

Install and first setup

Requires Node.js 20 or newer when installed through npm:

npm install -g secure-host-mcp
secure-host-mcp setup --public-url https://mcp.example.com
secure-host-mcp doctor
secure-host-mcp start

When run in an interactive terminal for a new installation, setup:

1. Asks whether the device has a directly reachable public IP and detects it through Cloudflare's trace endpoint when possible.
2. Inspects cloudflared and offers to install the checksum-verified official binary when it is missing. Installing the binary does not create a Cloudflare account or tunnel configuration.
3. Lets you automatically generate the initial token or enter any non-empty token of your choice. There is no fixed token format; letters, numbers, and combinations are accepted.
4. Explains that the same initial token is both the web-console administrator token and a full-access MCP Bearer token.
5. Prints concrete public-IP MCP and web-console URLs when a public IP is available, plus a plaintext HTTP warning.

Non-interactive setup keeps automation compatibility: it generates the token without prompting and does not install Cloudflare automatically. New installations listen on all network interfaces by default so remote clients can connect when the host firewall, router, and cloud security rules permit it.

Endpoints default to:

• MCP and OAuth: http://0.0.0.0:8767/mcp
• Administration: http://0.0.0.0:8768/

0.0.0.0 is a bind address, not a client URL. Connect with the server's IP address or DNS name. Both services start even when HTTPS is not configured, but authentication does not encrypt bearer tokens, OAuth codes, or administration traffic. ChatGPT requires a remotely reachable HTTPS MCP URL. Put Caddy, Nginx, Cloudflare Tunnel, frp, or another trusted reverse proxy in front of port 8767, and protect remote administration on port 8768 with HTTPS or a trusted private network. A minimal Caddy example is under examples/.

The administration URL serves a responsive bilingual dashboard after the administrator token is entered. It shows host resources and runtime configuration, creates and revokes scoped connection tokens, and controls configured frpc/cloudflared processes. Dashboard-created connection tokens are written to the same tokens.json registry used by setup and manual configuration.

For example, when setup detects 203.0.113.10, it prints:

Public MCP URL: http://203.0.113.10:8767/mcp
Web console URL: http://203.0.113.10:8768/
WARNING: HTTP is plaintext...

ChatGPT OAuth connection

Use https://mcp.example.com/mcp as the server URL and choose OAuth. The server publishes its authorization and protected-resource metadata. A new client dynamically registers, ChatGPT opens the authorization page, and the host administrator enters the administrator token and approves the requested scopes. The server uses authorization code + PKCE and issues rotating refresh tokens with offline access.

Full write-capable MCP support in ChatGPT depends on the account/workspace plan and current Developer Mode availability.

Terminal and jobs

The main MCP tools are execute_command, start_job, job_status, read_job_output, and cancel_job. Windows uses PowerShell 7 when available and Windows PowerShell otherwise. Linux uses /bin/bash unless configured differently.

Commands are not sandboxed or allowlisted. Run the service under a dedicated account unless full user/root access is intentional. execute_elevated fails closed until the process is already elevated or a privileged helper is installed. set_admin_mode records the request; service reconfiguration must be applied by an installed service adapter or the local CLI.

cloudflared and frpc

secure-host-mcp tunnel inspect
secure-host-mcp tunnel install-plan cloudflared
secure-host-mcp tunnel install-plan frpc
secure-host-mcp tunnel install cloudflared --yes
secure-host-mcp tunnel start cloudflared

The inspector searches PATH and standard cloudflared configuration directories. Set tunnels.frpcConfig for frpc. Parsed configuration is recursively redacted. frpc verify -c runs before launch. tunnels.proxyUrl is passed as HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, including socks5:// URLs supported by the selected tunnel client.

The install command requires --yes, downloads only the matching official GitHub Release asset, requires its published SHA-256 digest, verifies it, and installs to the application data directory. Without confirmation it fails closed.

Privileged helper

Normal service-account execution is the default. To enable per-command elevation, start the helper separately from an already elevated terminal:

# Windows: run PowerShell as Administrator
secure-host-mcp helper

sudo secure-host-mcp helper

The helper listens only on 127.0.0.1:8769, authenticates with a random key from the restricted secrets file, independently verifies that it is elevated, and audits complete command input/output. set_admin_mode(enabled=true) asks the helper to persist the mode, stop the ordinary instance, and start a new root/Administrator instance. Returning to a lower-privilege account requires restoring the configured Windows Service/systemd account locally; configuration alone is never treated as proof of elevation.

Security choices

• The configured administrator token has all scopes and is accepted by the web console, OAuth approval page, and direct MCP Bearer authentication.
• ~/.secure-host-mcp/tokens.json is the single registry for the administrator token and direct MCP connection tokens. OAuth grants and helper secrets live separately in secrets.json. Both files must use mode 0600 on POSIX. Back them up and protect them.
• Audit logs intentionally contain complete commands and stdout/stderr in plaintext. They rotate by size/day and are retained for 30 days under the data directory.
• MCP and administration listen on all interfaces by default. Every administration API request requires the administrator bearer token, and mutations also require the page CSRF token.
• Public HTTP is not encrypted: authentication controls access but cannot prevent interception of bearer tokens, OAuth codes, or administration traffic. Prefer HTTPS or a trusted VPN.
• Tool annotations ask compatible clients to confirm destructive operations. The host cannot prove that a client actually displayed a human confirmation.

Configuration

Set SECURE_HOST_MCP_HOME to change the data directory. Copy fields from config.example.json into the generated config.json, then restart. Configuration and secrets are written atomically.

The generated tokens.json is intentionally editable:

{
  "version": 1,
  "adminToken": "my-admin-token",
  "connectionTokens": [
    {
      "id": "second-agent",
      "token": "agent-2-token",
      "label": "Second agent",
      "scopes": ["system.read", "command.run"]
    }
  ]
}

Change adminToken to rotate the administrator token, or append entries to connectionTokens to create more direct MCP Bearer tokens. id is optional for manually added tokens; when omitted, the service derives a stable identifier from the token value. Token values have no pattern requirement but must be non-empty and unique. Scopes must come from system.read, command.run, command.elevate, tunnel.read, tunnel.manage, and admin.manage. Restart Secure Host MCP after manual edits. See tokens.example.json for a full-access example.

For a loopback-only deployment, explicitly set both mcp.host and admin.host to 127.0.0.1. New installations enable remote administration by default.

External OIDC can be enabled with auth.externalIssuer and auth.externalAudience. Tokens are verified against the issuer JWKS and mapped to the same MCP scopes.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

Standalone release builds use npm run package:standalone. Cross-platform artifacts should be produced and checksummed in release CI.

Publishing a release

Use Conventional Commit prefixes such as fix:, feat:, and feat!: when merging product changes into main. Release Please automatically creates or updates a Release PR containing the next package.json/lockfile version and CHANGELOG.md. While the project is below 1.0.0, both fix: and feat: produce patch releases; breaking changes retain their normal SemVer meaning.

Merging the Release PR creates the matching v<version> tag and GitHub Release. The release workflow then tests and packages both platforms, creates checksums, uploads the Windows/Linux assets to that Release, and publishes the same version to npm. The Release PR is never merged automatically, so publication retains an explicit review gate.

Explicit matching tags and guarded manual workflow runs remain available for recovery and prereleases. Prerelease versions use npm's next dist-tag; stable versions use latest.

The npm job uses Trusted Publishing with GitHub OIDC and does not require a long-lived npm token in repository secrets. A manual workflow run defaults to validation only and will not publish unless explicitly enabled.