MCP本地隧道工具

mcp-local-tunnel

Expose local MCP servers to remote clients — without opening ports.

Want to use local tools like shell-exec-mcp, computer-use-mcp, or filesystem-mcp from a remote MCP client like Claude.ai? Normally you'd need port forwarding, a static IP, or a VPN. mcp-local-tunnel removes all of that.

You run a relay on a server with a public URL, and an agent on your local machine. The agent connects outward to the relay over WebSocket — no inbound ports needed. The relay exposes a standard streamable HTTP MCP endpoint with OAuth 2.1 auth, so any MCP client can connect to it.

MCP client (Claude.ai, Cursor, etc.)
    |
    v
relay (tunnel.example.com)            you host this
    ^
    | outbound WebSocket
    |
agent (npx mcp-local-tunnel)          your laptop
    |
    v
local MCP servers                     stdio or HTTP

Both the relay and agent are the same mcp-local-tunnel package — you just set "mode": "relay" or "mode": "agent" in the config. It also works as an upstream in mcp-aggregator — the aggregator just sees another MCP server with tools.

Usage

Relay

Set MCP_LOCAL_TUNNEL_CONFIG to a JSON config object and run:

MCP_LOCAL_TUNNEL_CONFIG='{
  "mode": "relay",
  "auth": {"issuer": "https://auth.example.com"}
}' npx -y mcp-local-tunnel

This starts an HTTP MCP server on localhost:3000. MCP clients connect to /mcp with OAuth. Agents connect to /ws with a bearer token.

MCP_LOCAL_TUNNEL_CONFIG=/path/to/config.json npx -y mcp-local-tunnel

npx -y mcp-local-tunnel

docker run -e 'MCP_LOCAL_TUNNEL_CONFIG={"mode":"relay","auth":{"issuer":"..."}}' -p 3000:3000 ghcr.io/domdomegg/mcp-local-tunnel

Agent

MCP_LOCAL_TUNNEL_CONFIG='{
  "mode": "agent",
  "relay": "tunnel.example.com",
  "servers": {
    "shell": {"command": ["npx", "-y", "shell-exec-mcp"]},
    "computer": {"command": ["npx", "-y", "computer-use-mcp"]},
    "filesystem": {"command": ["npx", "-y", "filesystem-mcp"]}
  }
}' npx -y mcp-local-tunnel

On first run, the agent opens your browser for login (same identity provider as the relay). After authenticating, the token is cached in ~/.config/mcp-local-tunnel/ so subsequent runs connect immediately.

The agent spawns the configured local MCP servers, connects to the relay, and registers all their tools. Remote clients see tools like shell__execute and computer__computer — namespaced by server name.

When used as an MCP server in tools like Claude Code or opencode, the agent runs as a background daemon. Multiple sessions share a single relay connection — the daemon stays alive as long as at least one session exists, and shuts down automatically after the last session ends. Daemon logs are written to ~/.config/mcp-local-tunnel/logs/.

If the agent disconnects (laptop sleeps, network drops), it automatically reconnects with exponential backoff.

Config

Both modes use the same config loading: MCP_LOCAL_TUNNEL_CONFIG env var (JSON string or file path), or mcp-local-tunnel.config.json in the working directory.

Shared

Relay mode

Only mode and auth.issuer are required. Everything else has sensible defaults.

A full relay example:

{
  "mode": "relay",
  "auth": {
    "issuer": "https://keycloak.example.com/realms/myrealm",
    "clientId": "mcp-local-tunnel",
    "clientSecret": "optional-secret"
  },
  "port": 3000,
  "host": "0.0.0.0",
  "issuerUrl": "https://tunnel.example.com",
  "secret": "some-persistent-secret"
}

Agent mode

Only mode, relay, and servers are required.

A full agent example:

{
  "mode": "agent",
  "relay": "tunnel.example.com",
  "name": "my-laptop",
  "servers": {
    "shell": {
      "command": ["npx", "-y", "shell-exec-mcp"]
    },
    "computer": {
      "command": ["npx", "-y", "computer-use-mcp"]
    },
    "filesystem": {
      "command": ["npx", "-y", "filesystem-mcp"]
    }
  }
}

Login provider examples

{
  "mode": "relay",
  "auth": {
    "issuer": "https://accounts.google.com",
    "clientId": "...",
    "clientSecret": "..."
  }
}

{
  "mode": "relay",
  "auth": {
    "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
    "clientId": "...",
    "clientSecret": "..."
  }
}

{
  "mode": "relay",
  "auth": {
    "issuer": "https://your-org.okta.com",
    "clientId": "...",
    "clientSecret": "..."
  }
}

{
  "mode": "relay",
  "auth": {
    "issuer": "https://keycloak.example.com/realms/myrealm",
    "clientSecret": "..."
  }
}

{
  "mode": "relay",
  "auth": {
    "issuer": "https://your-tenant.auth0.com",
    "clientId": "...",
    "clientSecret": "..."
  }
}

{
  "mode": "relay",
  "auth": {
    "issuer": "https://authentik.example.com/application/o/myapp/",
    "clientSecret": "...",
    "userClaim": "preferred_username"
  }
}

{
  "mode": "relay",
  "auth": {
    "issuer": "https://hass-oidc-provider.example.com"
  }
}

Meta tools

The relay exposes two built-in tools:

• status — Shows whether an agent is connected, its device name, uptime, and available tools.
• restart — Tells connected agents to restart their local MCP server processes. Useful if a server is stuck or its configuration has changed.

These are always available, even when no agent is connected.

Multiple devices

If you run agents on multiple machines, the name field distinguishes them. Tools are prefixed with the device name when multiple devices are connected:

laptop__shell__execute
desktop__shell__execute

When only one device is connected, the device prefix is omitted.

Contributing

Pull requests are welcomed on GitHub! To get started:

1. Install Git and Node.js
2. Clone the repository
3. Install dependencies with npm install
4. Run npm run test to run tests
5. Build with npm run build

Releases

Versions follow the semantic versioning spec.

To release:

1. Use npm version <major | minor | patch> to bump the version
2. Run git push --follow-tags to push with tags
3. Wait for GitHub Actions to publish to the NPM registry and GHCR (Docker).