MCP Remote for Go

This Go implementation allows MCP clients that only support local (stdio) connections to connect to remote MCP servers with authentication support.

Overview

MCP Remote proxies between:

A local MCP client using stdio transport
A remote MCP server using Streamable HTTP or Server-Sent Events (SSE) with OAuth authentication

Features

Streamable HTTP transport (MCP 2025-11-25) - Single-endpoint POST/GET with session management
Legacy SSE transport (MCP 2024-11-05) - Traditional two-endpoint SSE connection
Auto-negotiation - Automatically detects server capabilities and selects the optimal transport
OAuth 2.1 with PKCE (RFC 7636) - Secure authorization with S256 code challenge
Protected Resource Metadata (RFC 9728) - Discover authorization servers from resource endpoints
OAuth Discovery (RFC 8414) and OpenID Connect Discovery
Custom headers and HTTPS enforcement

Installation

Desktop Extension (MCPB)

Download the .mcpb file for your platform from GitHub Releases:

Platform	File
macOS (Apple Silicon)	`mcp-remote-go-darwin-arm64.mcpb`
macOS (Intel)	`mcp-remote-go-darwin-amd64.mcpb`
Windows (x64)	`mcp-remote-go-windows-amd64.mcpb`
Windows (ARM64)	`mcp-remote-go-windows-arm64.mcpb`

Install by opening the .mcpb file in Claude Desktop. A configuration UI will appear where you can set the remote server URL and other options.

Building from Source

bash

# Clone the repository
git clone https://github.com/naotama2002/mcp-remote-go.git
cd mcp-remote-go

# Build the binary
make build

Using Docker

You can also run mcp-remote-go using Docker, which provides a consistent environment and easier deployment.

Pull from GitHub Container Registry

bash

# Pull the latest image
docker pull ghcr.io/naotama2002/mcp-remote-go:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/mcp-remote-go:{TAG}

Build locally

bash

# Build the Docker image
docker build -t mcp-remote-go .

Usage

Binary Usage

bash

# Basic usage (auto-detects transport: tries Streamable HTTP first, falls back to SSE)
mcp-remote-go https://remote.mcp.server/mcp

# Force Streamable HTTP transport
mcp-remote-go https://remote.mcp.server/mcp --transport streamable-http

# Force legacy SSE transport
mcp-remote-go https://remote.mcp.server/sse --transport sse

# With custom port for OAuth callback
mcp-remote-go https://remote.mcp.server/mcp 9090

# With custom headers (useful for auth bypass or adding auth tokens)
mcp-remote-go https://remote.mcp.server/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Allow HTTP for trusted networks (normally HTTPS is required)
mcp-remote-go http://internal.mcp.server/mcp --allow-http

# Via HTTP/HTTPS proxy
mcp-remote-go https://remote.mcp.server/mcp --https-proxy http://proxy.example.com:8080

Docker Usage

bash

# Basic usage with Docker (auto-detects transport)
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

# Force Streamable HTTP transport
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp --transport streamable-http

# Force legacy SSE transport
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse --transport sse

# With custom port for OAuth callback
docker run --rm -it -p 9090:9090 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp 9090

# With custom headers
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Allow HTTP for trusted networks
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest http://internal.mcp.server/mcp --allow-http

# Mount auth directory to persist OAuth tokens
docker run --rm -it -p 3334:3334 -v ~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

Configuration for MCP Clients

By default, mcp-remote-go auto-detects the transport (Streamable HTTP or SSE). You can force a specific transport with the --transport flag.

Claude Desktop (MCPB Extension)

The easiest way to use with Claude Desktop is via the .mcpb extension. After installing, configure through the GUI:

Setting	Description	Default
Remote MCP Server URL	The remote server URL (required)	—
Transport Mode	`auto`, `streamable-http`, or `sse`	`auto`
OAuth Callback Port	Local port for OAuth callback	`3334`
Allow HTTP	Allow insecure HTTP connections	`false`
HTTP/HTTPS Proxy	Proxy server URL (e.g. `http://proxy:8080`)	—
Authorization Header	Auth header value (stored securely)	—

Claude Desktop (Manual Configuration)

Edit the configuration file at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Using Binary

json

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Using Docker

json

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

For persistent OAuth tokens with Docker:

json

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "-v",
        "~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Cursor

Edit the configuration file at ~/.cursor/mcp.json:

Using Binary

json

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Using Docker

json

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Windsurf

Edit the configuration file at ~/.codeium/windsurf/mcp_config.json:

Using Binary

json

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Using Docker

json

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Environment Variables

All options can also be set via environment variables. CLI flags take precedence when both are set.

Variable	Description	Equivalent Flag
`MCP_SERVER_URL`	Remote MCP server URL	`--server`
`MCP_TRANSPORT`	Transport mode (`auto`, `streamable-http`, `sse`)	`--transport`
`MCP_PORT`	OAuth callback port	`--port`
`MCP_ALLOW_HTTP`	Set to `true` to allow HTTP	`--allow-http`
`MCP_HTTPS_PROXY`	HTTP/HTTPS proxy URL	`--https-proxy`
`MCP_AUTH_HEADER`	Authorization header value	`--header "Authorization: ..."`

These environment variables are used internally by the MCPB extension to pass GUI-configured values to the binary.

Authentication

The first time you connect to a server requiring authentication, you'll be prompted to open a URL in your browser to authorize access. The program will wait for you to complete the OAuth flow and then establish the connection. The callback port for OAuth authentication will automatically use an available port if the default port is in use.

The OAuth implementation supports:

PKCE (RFC 7636) with S256 code challenge for enhanced security
Protected Resource Metadata (RFC 9728) for discovering authorization servers
OAuth 2.0 Authorization Server Metadata (RFC 8414) and OpenID Connect Discovery

Authorization tokens are stored in ~/.mcp-remote-go-auth/ and will be reused for future connections.

Troubleshooting

Clear Authentication Data

If you're having issues with authentication, you can clear the stored data:

bash

rm -rf ~/.mcp-remote-go-auth

VPN/Certificate Issues

If you're behind a VPN and experiencing certificate issues, you might need to specify CA certificates:

bash

export SSL_CERT_FILE=/path/to/ca-certificates.crt
mcp-remote-go https://remote.mcp.server/sse

Docker Issues

Port Already in Use

If you get a "port already in use" error, either stop the conflicting service or use a different port:

bash

# Use a different port
docker run --rm -it -p 3335:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

Permission Issues with Volume Mount

If you have permission issues when mounting the auth directory:

bash

# Make sure the directory exists and has proper permissions
mkdir -p ~/.mcp-remote-go-auth
chmod 755 ~/.mcp-remote-go-auth

# Run with volume mount
docker run --rm -it -p 3334:3334 -v ~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

Network Issues with MCP Clients

If MCP clients can't connect to the Docker container, try using host networking:

bash

# Use host networking mode
docker run --rm -i --net=host ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

License

MIT

Mcp Remote Go

Documentation

MCP Remote for Go

Overview

Features

Installation

Desktop Extension (MCPB)

Building from Source

Using Docker

Pull from GitHub Container Registry

Build locally

Usage

Binary Usage

Docker Usage

Configuration for MCP Clients

Claude Desktop (MCPB Extension)

Claude Desktop (Manual Configuration)

Using Binary

Using Docker

Cursor

Using Binary

Using Docker

Windsurf

Using Binary

Using Docker

Environment Variables

Authentication

Troubleshooting

Clear Authentication Data

VPN/Certificate Issues

Docker Issues

Port Already in Use

Permission Issues with Volume Mount

Network Issues with MCP Clients

License

Similar MCP

Mcpjungle

Anyquery

Yutu

Mcp Cyclops

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Mcpjungle

Anyquery

Yutu

Mcp Cyclops

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare