[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72459":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":16,"starSnapshotCount":16,"syncStatus":34,"lastSyncTime":35,"discoverSource":36},72459,"mcp-proxy","sparfenyuk\u002Fmcp-proxy","sparfenyuk","A bridge between Streamable HTTP and stdio MCP transports","",null,"Python",2583,242,15,36,0,7,20,77,21,90.86,"MIT License",false,"main",[26,27,28,29,30],"mcp","mcp-server","proxy","sse","streamable-http","2026-06-12 04:01:05","# mcp-proxy\n\n![GitHub License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fsparfenyuk\u002Fmcp-proxy)\n![PyPI - Python Version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fmcp-proxy)\n![PyPI - Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmcp-proxy)\n[![codecov](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fsparfenyuk\u002Fmcp-proxy\u002Fgraph\u002Fbadge.svg?token=31VV9L7AZQ)](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fsparfenyuk\u002Fmcp-proxy)\n\n- [mcp-proxy](#mcp-proxy)\n  - [About](#about)\n  - [1. stdio to SSE\u002FStreamableHTTP](#1-stdio-to-ssestreamablehttp)\n    - [1.1 Configuration](#11-configuration)\n    - [1.2 Example usage](#12-example-usage)\n  - [2. SSE to stdio](#2-sse-to-stdio)\n    - [2.1 Configuration](#21-configuration)\n    - [2.2 Example usage](#22-example-usage)\n  - [Named Servers](#named-servers)\n  - [Installation](#installation)\n    - [Installing via PyPI](#installing-via-pypi)\n    - [Installing via Github repository (latest)](#installing-via-github-repository-latest)\n    - [Installing as container](#installing-as-container)\n    - [Troubleshooting](#troubleshooting)\n  - [Extending the container image](#extending-the-container-image)\n  - [Docker Compose Setup](#docker-compose-setup)\n  - [Command line arguments](#command-line-arguments)\n    - [Example config file](#example-config-file)\n  - [Testing](#testing)\n\n## About\n\nThe `mcp-proxy` is a tool that lets you switch between server transports. There are two supported modes:\n\n1. stdio to SSE\u002FStreamableHTTP\n2. SSE to stdio\n\n## 1. stdio to SSE\u002FStreamableHTTP\n\nRun a proxy server from stdio that connects to a remote SSE server.\n\nThis mode allows clients like Claude Desktop to communicate to a remote server over SSE even though it is not supported\nnatively.\n\n```mermaid\ngraph LR\n    A[\"Claude Desktop\"] \u003C--> |stdio| B[\"mcp-proxy\"]\n    B \u003C--> |SSE| C[\"External MCP Server\"]\n\n    style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px\n    style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px\n    style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px\n```\n\n### 1.1 Configuration\n\nThis mode requires providing the URL of the MCP Server's SSE endpoint as the program’s first argument. If the server uses Streamable HTTP transport, make sure to enforce it on the `mcp-proxy` side by passing `--transport=streamablehttp`.\n\nArguments\n\n| Name             | Required | Description                                                                                                       | Example                                       |\n| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |\n| `command_or_url` | Yes      | The MCP server SSE endpoint to connect to                                                                         | http:\u002F\u002Fexample.io\u002Fsse                         |\n| `--headers`      | No       | Headers to use for the MCP server SSE connection                                                                  | Authorization 'Bearer my-secret-access-token' |\n| `--transport`    | No       | Decides which transport protocol to use when connecting to an MCP server. Can be either 'sse' or 'streamablehttp' | streamablehttp                                |\n| `--client-id`    | No       | OAuth2 client ID for authentication                                                                               | your_client_id                                |\n| `--client-secret`| No       | OAuth2 client secret for authentication                                                                           | your_client_secret                            |\n| `--token-url`    | No       | OAuth2 token endpoint URL for authentication                                                                      | https:\u002F\u002Fauth.example.com\u002Foauth\u002Ftoken          |\n\nEnvironment Variables\n\n| Name               | Required | Description                                                                  | Example    |\n| ------------------ | -------- | ---------------------------------------------------------------------------- | ---------- |\n| `API_ACCESS_TOKEN` | No       | Can be used instead of `--headers Authorization 'Bearer \u003CAPI_ACCESS_TOKEN>'` | YOUR_TOKEN |\n\n### 1.2 Example usage\n\n`mcp-proxy` is supposed to be started by the MCP Client, so the configuration must be done accordingly.\n\nFor Claude Desktop, the configuration entry can look like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-proxy\": {\n      \"command\": \"mcp-proxy\",\n      \"args\": [\n        \"http:\u002F\u002Fexample.io\u002Fsse\"\n      ],\n      \"env\": {\n        \"API_ACCESS_TOKEN\": \"access-token\"\n      }\n    }\n  }\n}\n```\n\n## 2. SSE to stdio\n\nRun a proxy server exposing a SSE server that connects to a local stdio server.\n\nThis allows remote connections to the local stdio server. The `mcp-proxy` opens a port to listen for SSE requests,\nspawns a local stdio server that handles MCP requests.\n\n```mermaid\ngraph LR\n    A[\"LLM Client\"] \u003C-->|SSE| B[\"mcp-proxy\"]\n    B \u003C-->|stdio| C[\"Local MCP Server\"]\n\n    style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px\n    style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px\n    style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px\n```\n\n### 2.1 Configuration\n\nThis mode requires the `--sse-port` argument to be set. The `--sse-host` argument can be set to specify the host IP\naddress that the SSE server will listen on. Additional environment variables can be passed to the local stdio server\nusing the `--env` argument. The command line arguments for the local stdio server must be passed after the `--`\nseparator.\n\nArguments\n\n| Name                                 | Required                   | Description                                                                                   | Example                                     |\n| ------------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------- |\n| `command_or_url`                     | Yes                        | The command to spawn the MCP stdio server                                                     | uvx mcp-server-fetch                        |\n| `--port`                             | No, random available       | The MCP server port to listen on                                                              | 8080                                        |\n| `--host`                             | No, `127.0.0.1` by default | The host IP address that the MCP server will listen on                                        | 0.0.0.0                                     |\n| `--env`                              | No                         | Additional environment variables to pass to the MCP stdio server. Can be used multiple times. | FOO BAR                                     |\n| `--cwd`                              | No                         | The working directory to pass to the MCP stdio server process.                                | \u002Ftmp                                        |\n| `--pass-environment`                 | No                         | Pass through all environment variables when spawning the server                               | --no-pass-environment                       |\n| `--allow-origin`                     | No                         | Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.   | --allow-origin \"\\*\"                         |\n| `--expose-header`                    | No                         | Headers added to `Access-Control-Expose-Headers`. Can be used multiple times. Defaults to `mcp-session-id`. | --expose-header Custom-Header              |\n| `--stateless`                        | No                         | Enable stateless mode for streamable http transports. Default is False                        | --no-stateless                              |\n| `--named-server NAME COMMAND_STRING` | No                         | Defines a named stdio server.                                                                 | --named-server fetch 'uvx mcp-server-fetch' |\n| `--named-server-config FILE_PATH`    | No                         | Path to a JSON file defining named stdio servers.                                             | --named-server-config \u002Fpath\u002Fto\u002Fservers.json |\n| `--sse-port` (deprecated)            | No, random available       | The SSE server port to listen on                                                              | 8080                                        |\n| `--sse-host` (deprecated)            | No, `127.0.0.1` by default | The host IP address that the SSE server will listen on                                        | 0.0.0.0                                     |\n\n### 2.2 Example usage\n\nTo start the `mcp-proxy` server that listens on port 8080 and connects to the local MCP server:\n\n```bash\n# Start the MCP server behind the proxy\nmcp-proxy uvx mcp-server-fetch\n\n# Start the MCP server behind the proxy with a custom port\n# (deprecated) mcp-proxy --sse-port=8080 uvx mcp-server-fetch\nmcp-proxy --port=8080 uvx mcp-server-fetch\n\n# Start the MCP server behind the proxy with a custom host and port\n# (deprecated) mcp-proxy --sse-host=0.0.0.0 --sse-port=8080 uvx mcp-server-fetch\nmcp-proxy --host=0.0.0.0 --port=8080 uvx mcp-server-fetch\n\n# Start the MCP server behind the proxy with a custom user agent\n# Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments\n# (deprecated) mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent\nmcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent\n\n# Start multiple named MCP servers behind the proxy\nmcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch'\n\n# Start multiple named MCP servers using a configuration file\nmcp-proxy --port=8080 --named-server-config .\u002Fservers.json\n\n# Start the MCP server with CORS enabled and custom exposed headers\nmcp-proxy --port=8080 --allow-origin='*' --expose-header Custom-Header uvx mcp-server-fetch\n```\n\n## Named Servers\n\n- `NAME` is used in the URL path `\u002Fservers\u002FNAME\u002F`.\n- `COMMAND_STRING` is the command to start the server (e.g., 'uvx mcp-server-fetch').\n  - Can be used multiple times.\n  - This argument is ignored if `--named-server-config` is used.\n- `FILE_PATH` - If provided, this is the exclusive source for named servers, and `--named-server` CLI arguments are ignored.\n\nIf a default server is specified (the `command_or_url` argument without `--named-server` or `--named-server-config`), it will be accessible at the root paths (e.g., `http:\u002F\u002F127.0.0.1:8080\u002Fsse`).\n\nNamed servers (whether defined by `--named-server` or `--named-server-config`) will be accessible under `\u002Fservers\u002F\u003Cserver-name>\u002F` (e.g., `http:\u002F\u002F127.0.0.1:8080\u002Fservers\u002Ffetch1\u002Fsse`).\nThe `\u002Fstatus` endpoint provides global status.\n\n**JSON Configuration File Format for `--named-server-config`:**\n\nThe JSON file should follow this structure:\n\n```json\n{\n  \"mcpServers\": {\n    \"fetch\": {\n      \"disabled\": false,\n      \"timeout\": 60,\n      \"command\": \"uvx\",\n      \"args\": [\n        \"mcp-server-fetch\"\n      ],\n      \"transportType\": \"stdio\"\n    },\n    \"github\": {\n      \"timeout\": 60,\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol\u002Fserver-github\"\n      ],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\u003CYOUR_TOKEN>\"\n      },\n      \"transportType\": \"stdio\"\n    }\n  }\n}\n```\n\n- `mcpServers`: A dictionary where each key is the server name (used in the URL path, e.g., `\u002Fservers\u002Ffetch\u002F`) and the value is an object defining the server.\n- `command`: (Required) The command to execute for the stdio server.\n- `args`: (Optional) A list of arguments for the command. Defaults to an empty list.\n- `enabled`: (Optional) If `false`, this server definition will be skipped. Defaults to `true`.\n- `timeout` and `transportType`: These fields are present in standard MCP client configurations but are currently **ignored** by `mcp-proxy` when loading named servers. The transport type is implicitly \"stdio\".\n\n## Installation\n\n### Installing via PyPI\n\nThe stable version of the package is available on the PyPI repository. You can install it using the following command:\n\n```bash\n# Option 1: With uv (recommended)\nuv tool install mcp-proxy\n\n# Option 2: With pipx (alternative)\npipx install mcp-proxy\n```\n\nOnce installed, you can run the server using the `mcp-proxy` command. See configuration options for each mode above.\n\n### Installing via Github repository (latest)\n\nThe latest version of the package can be installed from the git repository using the following command:\n\n```bash\nuv tool install git+https:\u002F\u002Fgithub.com\u002Fsparfenyuk\u002Fmcp-proxy\n```\n\n> [!NOTE]\n> If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.\n\n> [!NOTE]\n> If you want to delete the server, use the `uv tool uninstall mcp-proxy` command.\n\n### Installing as container\n\nStarting from version 0.3.2, it's possible to pull and run the corresponding container image.\nRelease images are published to GHCR and Docker Hub as multi-platform manifests for `linux\u002Famd64` and `linux\u002Farm64`;\nDocker selects the matching image for the host architecture automatically.\n\n```bash\ndocker run --rm -t ghcr.io\u002Fsparfenyuk\u002Fmcp-proxy:v0.12.0 --help\ndocker run --rm -t sparfenyuk\u002Fmcp-proxy:v0.12.0 --help\n```\n\n### Troubleshooting\n\n- **Problem**: Claude Desktop can't start the server: ENOENT code in the logs\n\n  **Solution**: Try to use the full path to the binary. To do so, open a terminal and run the command`which mcp-proxy` (\n  macOS, Linux) or `where.exe mcp-proxy` (Windows). Then, use the output path as a value for 'command' attribute:\n  ```json\n    \"fetch\": {\n      \"command\": \"\u002Ffull\u002Fpath\u002Fto\u002Fbin\u002Fmcp-proxy\",\n      \"args\": [\n        \"http:\u002F\u002Flocalhost:8932\u002Fsse\"\n      ]\n    }\n  ```\n\n## Extending the container image\n\nYou can extend the `mcp-proxy` container image to include additional executables. For instance, `uv` is not included by\ndefault, but you can create a custom image with it:\n\n```Dockerfile\n# file: mcp-proxy.Dockerfile\n\nFROM ghcr.io\u002Fsparfenyuk\u002Fmcp-proxy:latest\n\n# Install the 'uv' package\nRUN python3 -m ensurepip && pip install --no-cache-dir uv\n\nENV PATH=\"\u002Fusr\u002Flocal\u002Fbin:$PATH\" \\\n    UV_PYTHON_PREFERENCE=only-system\n\nENTRYPOINT [\"catatonit\", \"--\", \"mcp-proxy\"]\n```\n\n## Docker Compose Setup\n\nWith the custom Dockerfile, you can define a service in your Docker Compose file:\n\n```yaml\nservices:\n  mcp-proxy-custom:\n    build:\n      context: .\n      dockerfile: mcp-proxy.Dockerfile\n    network_mode: host\n    restart: unless-stopped\n    ports:\n      - 8096:8096\n    command: \"--pass-environment --port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch\"\n```\n\n> [!NOTE]\n> Don't forget to set `--pass-environment` argument, otherwise you'll end up with the error \"No interpreter found in\n> managed installations or search path\"\n\n## Command line arguments\n\n```bash\nusage: mcp-proxy [-h] [--version] [-H KEY VALUE]\n                 [--transport {sse,streamablehttp}] [--verify-ssl [VALUE]]\n                 [--no-verify-ssl] [-e KEY VALUE] [--cwd CWD]\n                 [--client-id CLIENT_ID] [--client-secret CLIENT_SECRET] [--token-url TOKEN_URL]\n                 [--pass-environment | --no-pass-environment]\n                 [--log-level LEVEL] [--debug | --no-debug]\n                 [--named-server NAME COMMAND_STRING]\n                 [--named-server-config FILE_PATH] [--port PORT] [--host HOST]\n                 [--stateless | --no-stateless] [--sse-port SSE_PORT]\n                 [--sse-host SSE_HOST]\n                 [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]\n                 [--expose-header HEADER]\n                 [command_or_url] [args ...]\n\nStart the MCP proxy in one of two possible modes: as a client or a server.\n\npositional arguments:\n  command_or_url        Command or URL to connect to. When a URL, will run an SSE\u002FStreamableHTTP client. Otherwise, if --named-server is not used, this will be the command for the default stdio client. If --named-server is used, this argument is ignored for stdio mode unless no default server is desired. See corresponding options for more details.\n\noptions:\n  -h, --help            show this help message and exit\n  --version             Show the version and exit\n\nSSE\u002FStreamableHTTP client options:\n  -H, --headers KEY VALUE\n                        Headers to pass to the SSE server. Can be used multiple times.\n  --transport {sse,streamablehttp}\n                        The transport to use for the client. Default is SSE.\n  --verify-ssl [VALUE]  Control SSL verification when acting as a client. Use without a value to force verification, pass 'false' to disable, or provide a path to a PEM bundle.\n  --no-verify-ssl       Disable SSL verification (alias for --verify-ssl false).\n  --client-id CLIENT_ID\n                        OAuth2 client ID for authentication\n  --client-secret CLIENT_SECRET\n                        OAuth2 client secret for authentication\n  --token-url TOKEN_URL\n                        OAuth2 token URL for authentication\n\nstdio client options:\n  args                  Any extra arguments to the command to spawn the default server. Ignored if only named servers are defined.\n  -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.\n  --cwd CWD             The working directory to use when spawning the default server process. Named servers inherit the proxy's CWD.\n  --pass-environment, --no-pass-environment\n                        Pass through all environment variables when spawning all server processes.\n  --log-level LEVEL     Set the log level. Default is INFO.\n  --debug, --no-debug   Enable debug mode with detailed logging output. Equivalent to --log-level DEBUG. If both --debug and --log-level are provided, --debug takes precedence.\n  --named-server NAME COMMAND_STRING\n                        Define a named stdio server. NAME is for the URL path \u002Fservers\u002FNAME\u002F. 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.\n  --named-server-config FILE_PATH\n                        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.\n\nSSE server options:\n  --port PORT           Port to expose an SSE server on. Default is a random port\n  --host HOST           Host to expose an SSE server on. Default is 127.0.0.1\n  --stateless, --no-stateless\n                        Enable stateless mode for streamable http transports. Default is False\n  --sse-port SSE_PORT   (deprecated) Same as --port\n  --sse-host SSE_HOST   (deprecated) Same as --host\n  --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]\n                        Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.\n  --expose-header HEADER\n                        Headers to expose via Access-Control-Expose-Headers. Defaults to 'Mcp-Session-Id'. Can be used multiple times.\n\nExamples:\n  mcp-proxy http:\u002F\u002Flocalhost:8080\u002Fsse\n  mcp-proxy --no-verify-ssl https:\u002F\u002Fserver.local\u002Fsse\n  mcp-proxy --transport streamablehttp http:\u002F\u002Flocalhost:8080\u002Fmcp\n  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http:\u002F\u002Flocalhost:8080\u002Fsse\n  mcp-proxy --client-id CLIENT_ID --client-secret CLIENT_SECRET --token-url https:\u002F\u002Fauth.example.com\u002Ftoken http:\u002F\u002Flocalhost:8080\u002Fsse\n  mcp-proxy --port 8080 -- your-command --arg1 value1 --arg2 value2\n  mcp-proxy --named-server fetch 'uvx mcp-server-fetch' --port 8080\n  mcp-proxy your-command --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE\n  mcp-proxy your-command --port 8080 --allow-origin='*'\n  mcp-proxy your-command --port 8080 --allow-origin='*' --expose-header Custom-Header\n```\n\n### Example config file\n\n```json\n{\n  \"mcpServers\": {\n    \"fetch\": {\n      \"enabled\": true,\n      \"timeout\": 60,\n      \"command\": \"uvx\",\n      \"args\": [\n        \"mcp-server-fetch\"\n      ],\n      \"transportType\": \"stdio\"\n    },\n    \"github\": {\n      \"timeout\": 60,\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol\u002Fserver-github\"\n      ],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\u003CYOUR_TOKEN>\"\n      },\n      \"transportType\": \"stdio\"\n    }\n  }\n}\n```\n\n## Testing\n\nCheck the `mcp-proxy` server by running it with the `mcp-server-fetch` server. You can use\nthe [inspector tool](https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Ftools\u002Finspector) to test the target server.\n\n```bash\n# Run the stdio server called mcp-server-fetch behind the proxy over SSE\nmcp-proxy --port=8080 uvx mcp-server-fetch &\n\n# Connect to the SSE proxy server spawned above using another instance of mcp-proxy given the URL of the SSE server\nmcp-proxy http:\u002F\u002F127.0.0.1:8080\u002Fsse\n\n# Send CTRL+C to stop the second server\n\n# Bring the first server to the foreground\nfg\n\n# Send CTRL+C to stop the first server\n```\n","mcp-proxy 是一个用于在 Streamable HTTP 和 stdio 之间进行转换的工具。它支持两种主要模式：从 stdio 到 SSE\u002FStreamableHTTP 以及从 SSE 到 stdio 的转换，从而使得像 Claude Desktop 这样的客户端能够通过 SSE 与远程服务器通信，即使这些客户端本身不直接支持这种传输方式。项目采用 Python 编写，并且可以通过多种方式进行安装，包括 PyPI、GitHub 仓库和 Docker 容器等。适用于需要将基于标准输入输出的应用程序与使用 Server-Sent Events 或 Streamable HTTP 协议的服务进行桥接的场景。",2,"2026-06-11 03:42:08","high_star"]