MCP SSE Proxy

Description

This script acts as a proxy between an MCP (Model Context Protocol) server using STDIO (standard input/output) transport and a client using SSE (Server-Sent Events) transport. It bridges the communication gap by converting MCP STDIO communication to the SSE protocol, enabling real-time data streaming over web connections.

Communication Diagram:

[App](STDIO) ----<>---- (STDIO)[PROXY](SSE) ----<>---- (SSE)[SSE-Server]

flowchart LR
    App -- STDIO --> PROXY
    PROXY -- SSE --> SSEServer
    PROXY -- STDIO --> App
    SSEServer -- SSE --> PROXY
    SSEServer["SSE-Server"]
    App["APP"] 

    App@{ icon: "gcp:tools-for-powershell", form: "square", pos: "b"}
    SSEServer@{ icon: "aws:res-toolkit", form: "square", pos: "b"}

Usage

To run the MCP SSE Proxy, execute the mcp_sse_proxy.py script with the required --sse-url or ST_PROXY_SSE_URL environment variable, which specifies the URL of your SSE server endpoint. This is the only required mandatory parameter.

Installation

pip3 install mcp-sse-proxy
python3 -m mcp_sse_proxy -h

The package installer (pip) creates an executable script in the bin directory of your virtual environment (or Python installation). If you are in a virtual environment, you can run the script using directly as a command.

mcp-sse-proxy -h

Before you start

If you do installation by copy-past, remember to install dependencies:

pip3 install -r requirements.txt

Configuration

Command-line Arguments

• --sse-url <url>: (Required) The URL of the external SSE endpoint to connect to. You can also set this using the ST_PROXY_SSE_URL environment variable.
• --debug-enabled: Enable debug logging. You can also set this using the ST_PROXY_DEBUG_ENABLED environment variable (set to true to enable).
• --ping-interval <seconds>: Set the interval (in seconds) for sending ping messages to maintain the SSE connection. Default is 10 seconds. You can also set this using the ST_PROXY_PING_INTERVAL environment variable.

Environment Variables

The proxy can be configured using the following environment variables:

• ST_PROXY_SSE_URL: URL of the external SSE endpoint.
• ST_PROXY_DEBUG_ENABLED: Enable debug logging (set to true to enable).
• ST_PROXY_DEBUG_FILENAME: Filename for the debug log file. Defaults to mcp_sse_proxy.log.
• ST_PROXY_PING_INTERVAL: Ping interval in seconds.
• ST_PROXY_ENV_PREFIXES: Comma-separated list of environment variable prefixes to forward to the proxied application. This allows you to pass specific environment variables through the proxy. For example: ANTHROPIC_,OPENAI_,GEMINI_.

Claude AI configuration example

Windows Config location: C:\Users<USERNAME>\AppData\Roaming\Claude\claude_desktop_config [or open via clinent menu: File->Settings then Developer->Edit Config] Config example for Windows:

{
  "globalShortcut": "",
  "mcpServers": {
    "mcp-sse-proxy": {
      "command": "C:\\Users\\<USERNAME>\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": [
        "C:\\mcp-sse-proxy-claude\\src\\mcp_sse_proxy.py",
		"--base-url", "http://<IP_ADDRESS>:8000",
		"--debug-enabled"
      ],
	  "env": {
		  "OPENAI_API_KEY": "sk-xxx",
		  "BRAVE_API_KEY": "BSAxxxx",
		  "ST_PROXY_ENV_PREFIXES": "OPENAI_,BRAVE_"
	  }
    }
  }
}

Debug Logging

Debug logging can be enabled using the --debug-enabled command-line argument or by setting the ST_PROXY_DEBUG_ENABLED environment variable to true. When enabled, detailed logs are written to the file specified by the ST_PROXY_DEBUG_FILENAME environment variable (default: mcp_sse_proxy.log).

Ping Interval

To ensure the SSE connection remains active, the proxy sends ping messages to the SSE server at regular intervals. The default interval is 10 seconds, configurable via the --ping-interval argument or the `ST_PROXY_PING_INTERV

... View full README on GitHub