graph LR A["Claude Desktop"] <--> |stdio| B["mcp-proxy"] B <--> |SSE| C["External MCP Server"] style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px

{ "mcpServers": { "mcp-proxy": { "command": "mcp-proxy", "args": [ "http://example.io/sse" ], "env": { "API_ACCESS_TOKEN": "access-token" } } } }

graph LR A["LLM Client"] <-->|SSE| B["mcp-proxy"] B <-->|stdio| C["Local MCP Server"] style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px

# Start the MCP server behind the proxy mcp-proxy uvx mcp-server-fetch # Start the MCP server behind the proxy with a custom port # (deprecated) mcp-proxy --sse-port=8080 uvx mcp-server-fetch mcp-proxy --port=8080 uvx mcp-server-fetch # Start the MCP server behind the proxy with a custom host and port # (deprecated) mcp-proxy --sse-host=0.0.0.0 --sse-port=8080 uvx mcp-server-fetch mcp-proxy --host=0.0.0.0 --port=8080 uvx mcp-server-fetch # Start the MCP server behind the proxy with a custom user agent # Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments # (deprecated) mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent # Start multiple named MCP servers behind the proxy mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch' # Start multiple named MCP servers using a configuration file mcp-proxy --port=8080 --named-server-config ./servers.json

{ "mcpServers": { "fetch": { "disabled": false, "timeout": 60, "command": "uvx", "args": [ "mcp-server-fetch" ], "transportType": "stdio" }, "github": { "timeout": 60, "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "transportType": "stdio" } } }

npx -y @smithery/cli install mcp-proxy --client claude

# Option 1: With uv (recommended) uv tool install mcp-proxy # Option 2: With pipx (alternative) pipx install mcp-proxy

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

docker run -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help

# file: mcp-proxy.Dockerfile FROM ghcr.io/sparfenyuk/mcp-proxy:latest # Install the 'uv' package RUN python3 -m ensurepip && pip install --no-cache-dir uv ENV PATH="/usr/local/bin:$PATH" \ UV_PYTHON_PREFERENCE=only-system ENTRYPOINT [ "mcp-proxy" ]

services: mcp-proxy-custom: build: context: . dockerfile: mcp-proxy.Dockerfile network_mode: host restart: unless-stopped ports: - 8096:8096 command: "--pass-environment --port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"

usage: mcp-proxy [-h] [-H KEY VALUE] [--transport {sse,streamablehttp}] [-e KEY VALUE] [--cwd CWD] [--pass-environment | --no-pass-environment] [--debug | --no-debug] [--named-server NAME COMMAND_STRING] [--named-server-config FILE_PATH] [--port PORT] [--host HOST] [--stateless | --no-stateless] [--sse-port SSE_PORT] [--sse-host SSE_HOST] [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]] [command_or_url] [args ...] Start the MCP proxy. It can run as an SSE client (connecting to a remote SSE server and exposing stdio). Or, it can run as an SSE server (connecting to local stdio command(s) and exposing them over SSE). When running as an SSE server, it can proxy a single default stdio command or multiple named stdio commands (defined via CLI or a config file). positional arguments: command_or_url Command or URL. If URL (http/https): Runs in SSE/StreamableHTTP client mode. If command string: Runs in SSE server mode, this is the default stdio server. If --named-server or --named-server-config is used, this can be omitted if no default server is desired. options: -h, --help show this help message and exit SSE/StreamableHTTP client options: -H, --headers KEY VALUE Headers to pass to the SSE server. Can be used multiple times. --transport {sse,streamablehttp} The transport to use for the client. Default is SSE. stdio client options: args Any extra arguments to the command to spawn the default server. Ignored if only named servers are defined. -e, --env KEY VALUE Environment variables used when spawning the default server. Can be used multiple times. For named servers, environment is inherited or passed via --pass-environment. --cwd CWD The working directory to use when spawning the default server process. Named servers inherit the proxy's CWD. --pass-environment, --no-pass-environment Pass through all environment variables when spawning all server processes. --debug, --no-debug Enable debug mode with detailed logging output. --named-server NAME COMMAND_STRING Define a named stdio server. NAME is for the URL path /servers/NAME/. COMMAND_STRING is a single string with the command and its arguments (e.g., 'uvx mcp-server-fetch --timeout 10'). These servers inherit the proxy's CWD and environment from --pass-environment. Can be specified multiple times. Ignored if --named-server-config is used. --named-server-config FILE_PATH Path to a JSON configuration file for named stdio servers. If provided, this will be the exclusive source for named server definitions, and any --named-server CLI arguments will be ignored. SSE server options: --port PORT Port to expose an SSE server on. Default is a random port --host HOST Host to expose an SSE server on. Default is 127.0.0.1 --stateless, --no-stateless Enable stateless mode for streamable http transports. Default is False --sse-port SSE_PORT (deprecated) Same as --port --sse-host SSE_HOST (deprecated) Same as --host --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...] Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed. Examples: mcp-proxy http://localhost:8080/sse mcp-proxy --transport streamablehttp http://localhost:8080/mcp mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse mcp-proxy --port 8080 -- my-default-command --arg1 value1 mcp-proxy --port 8080 --named-server fetch1 'uvx mcp-server-fetch' --named-server tool2 'my-custom-tool --verbose' mcp-proxy --port 8080 --named-server-config /path/to/servers.json mcp-proxy --port 8080 --named-server-config /path/to/servers.json -- my-default-command --arg1 mcp-proxy --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE -- my-default-command mcp-proxy --port 8080 --allow-origin='*' -- my-default-command

{ "mcpServers": { "fetch": { "enabled": true, "timeout": 60, "command": "uvx", "args": [ "mcp-server-fetch" ], "transportType": "stdio" }, "github": { "timeout": 60, "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "transportType": "stdio" } } }

# Run the stdio server called mcp-server-fetch behind the proxy over SSE mcp-proxy --port=8080 uvx mcp-server-fetch & # Connect to the SSE proxy server spawned above using another instance of mcp-proxy given the URL of the SSE server mcp-proxy http://127.0.0.1:8080/sse # Send CTRL+C to stop the second server # Bring the first server to the foreground fg # Send CTRL+C to stop the first server