mcp-claude-bridge

A tiny, dependency-free Go binary that lets any stdio-only MCP client (e.g. Claude Desktop) talk to a remote MCP server that speaks the SSE transport.

If your MCP server runs on another machine, inside a container, or behind a reverse proxy, Claude Desktop can't reach it directly — Claude only knows how to launch a local process and speak MCP over stdin/stdout. mcp-claude-bridge is that local process: it reads stdio frames from Claude on one side and speaks SSE + HTTP POST to the remote server on the other.

┌──────────────┐   stdio    ┌────────────────────┐   SSE + POST   ┌────────────┐
│ Claude       │◄──────────►│ mcp-claude-bridge  │◄──────────────►│ MCP server │
│ Desktop      │            │  (this repo)       │                │ (remote)   │
└──────────────┘            └────────────────────┘                └────────────┘

Features

• Bi-directional bridging: stdio ↔ SSE GET stream + HTTP POST message endpoint
• Flexible input framing: accepts both LSP-style Content-Length frames and plain JSON-per-line
• Multiple headers: pass --header repeatedly for auth tokens, tenant IDs, etc.
• Automatic reconnect with capped exponential backoff (--reconnect)
• Graceful shutdown on SIGINT/SIGTERM
• Zero runtime dependencies — pure Go, single static binary
• Works on Windows, macOS, and Linux

Quickstart

Install

Download the latest binary for your platform from the project's GitHub Releases page, or build from source:

git clone https://github.com/LennardGeissler/mcp-claude-bridge.git
cd mcp-claude-bridge
go build -trimpath -ldflags "-s -w" -o mcp-claude-bridge ./cmd/mcp-claude-bridge

Go 1.22 or newer is required. On Windows, the produced file is mcp-claude-bridge.exe.

Note on go install: this project deliberately uses a neutral Go module path (mcp-claude-bridge) so that no specific GitHub org is hardcoded into the source. As a side effect, go install github.com/...@latest is not supported — please git clone and go build, or use a pre-built release binary.

Run it against a local mock

./mcp-claude-bridge --url https://your-mcp-host:5183/mcp --debug

Pass MCP JSON on stdin. Responses appear on stdout, one JSON document per line.

Two ready-to-pipe payloads live under examples/requests/ for a quick smoke test:

cat examples/requests/initialize.json | ./mcp-claude-bridge --url https://your-mcp-host:5183/mcp --debug
cat examples/requests/ping.json       | ./mcp-claude-bridge --url https://your-mcp-host:5183/mcp --debug

Use it from Claude Desktop

Edit your Claude Desktop config file:

OS	Path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add an entry under mcpServers:

{
  "mcpServers": {
    "my-remote-server": {
      "command": "C:\\Tools\\mcp-claude-bridge.exe",
      "args": [
        "--url", "https://mcp.internal:5183/mcp",
        "--header", "Authorization: Bearer s3cret",
        "--reconnect"
      ]
    }
  }
}

On macOS/Linux the command is just the absolute path to the binary. Restart Claude Desktop after editing the file.

CLI flags

Flag	Default	Description
--url	(required)	Remote MCP SSE URL, e.g. https://host:5183/mcp
--header	(none)	Extra request header Key: Value. Repeatable.
--post-timeout	15s	Timeout for a single outbound POST
--sse-header-timeout	15s	Timeout for the SSE response headers on connect
--reconnect	false	Reconnect SSE after transport errors
--reconnect-backoff	2s	Initial backoff between reconnect attempts (capped at 30s, doubles on each retry)
--insecure-skip-verify	false	Disable TLS verification. Do not use in production.
--debug	false	Verbose logging to stderr

Run mcp-claude-bridge -h to see this list at runtime.

How input framing works

Real-world MCP clients don't all agree on a framing. The bridge accepts both common forms:

LSP-style framed input (used by some SDKs):

Content-Length: 48\r\n
\r\n
{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}

Plain JSON per line (used by Claude Desktop today):

{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}\n

The bridge detects which is in use per message by peeking at the first non-whitespace byte. Output on stdout is always a single JSON document followed by \n, which both framings handle.

Security

• TLS: Always prefer proper certificates. If your remote server uses a certificate signed by an internal CA, deploy that CA to your OS trust store (Windows: Trusted Root Certification Authorities; macOS: System keychain; Linux: /etc/ssl/certs + update-ca-certificates). That is how you get working HTTPS — not by disabling verification.
• --insecure-skip-verify: skips certificate verification entirely. This makes your connection vulnerable to trivial man-in-the-middle attacks. Use it only for local development against self-signed certs on localhost, and never commit Claude Desktop config with this flag set for a production host.
• Credentials in headers: values passed via --header end up in the Claude Desktop config file in plaintext. Treat that file as a secret and lock down its permissions. Prefer short-lived tokens where possible.
• Process isolation: the bridge runs as the same user as Claude Desktop. It has no special privileges and only connects to the single URL you specify.

Vulnerability reports are welcome — see SECURITY.md.

Contributing

Patches, tests, and bug reports are welcome. Please read CONTRIBUTING.md and our CODE_OF_CONDUCT.md first.

License

MIT