{"id":23937077,"url":"https://github.com/sparfenyuk/mcp-proxy","last_synced_at":"2025-05-15T11:04:35.603Z","repository":{"id":271641347,"uuid":"908734690","full_name":"sparfenyuk/mcp-proxy","owner":"sparfenyuk","description":"Connect to MCP servers that run on SSE transport, or expose stdio servers as an SSE server using the MCP Proxy server.","archived":false,"fork":false,"pushed_at":"2025-03-25T08:39:32.000Z","size":126,"stargazers_count":327,"open_issues_count":6,"forks_count":45,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-05T20:01:32.300Z","etag":null,"topics":["mcp","mcp-server","proxy","sse"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sparfenyuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-26T20:31:54.000Z","updated_at":"2025-04-05T16:22:51.000Z","dependencies_parsed_at":"2025-03-22T18:01:10.689Z","dependency_job_id":"3606c35e-58e4-44b1-8ddd-0e34972f4893","html_url":"https://github.com/sparfenyuk/mcp-proxy","commit_stats":null,"previous_names":["sparfenyuk/mcp-proxy"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparfenyuk%2Fmcp-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparfenyuk%2Fmcp-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparfenyuk%2Fmcp-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sparfenyuk%2Fmcp-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sparfenyuk","download_url":"https://codeload.github.com/sparfenyuk/mcp-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248537146,"owners_count":21120711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","proxy","sse"],"created_at":"2025-01-06T02:00:30.854Z","updated_at":"2025-05-15T11:04:35.596Z","avatar_url":"https://github.com/sparfenyuk.png","language":"Python","funding_links":[],"categories":["Aggregators \u0026 Gateways","实ē”Øå·„å…·","Agent workflow highlights","Python","šŸ“š Projects (1974 total)","Community Servers","šŸ¤– AI/ML","ć‚µćƒ¼ćƒćƒ¼å®Ÿč£…","Utilities","MCP SDK","Real-Time Collaboration","MCP Utilities \u0026 Tools","šŸ“‚ ģ¹“ķ…Œź³ ė¦¬","MCP Middleware \u0026 Orchestration","Table of Contents","šŸ—‚ļø Extensions by Category"],"sub_categories":["Gateways \u0026 Proxies","MCP Servers","šŸ› ļø \u003ca name=\"other-tools-and-integrations\"\u003e\u003c/a\u003ećć®ä»–ć®ćƒ„ćƒ¼ćƒ«ćØēµ±åˆ","šŸ› ļø \u003ca name=\"other-tools-and-integrations\"\u003e\u003c/a\u003eOther Tools and Integrations","šŸ› ļø Other Tools and Integrations","Gateways","šŸ”§ Utilities","Other Tools and Integrations","šŸ”§ MCP Tools","Proxies and Gateways"],"readme":"# mcp-proxy\n\n![GitHub License](https://img.shields.io/github/license/sparfenyuk/mcp-proxy)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mcp-proxy)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/mcp-proxy)\n[![codecov](https://codecov.io/gh/sparfenyuk/mcp-proxy/graph/badge.svg?token=31VV9L7AZQ)](https://codecov.io/gh/sparfenyuk/mcp-proxy)\n[![smithery badge](https://smithery.ai/badge/mcp-proxy)](https://smithery.ai/server/mcp-proxy)\n\n- [mcp-proxy](#mcp-proxy)\n - [About](#about)\n - [1. stdio to SSE/StreamableHttp](#1-stdio-to-sse)\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 - [Installation](#installation)\n - [Installing via Smithery](#installing-via-smithery)\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 - [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/StreamableHTTP\n2. SSE to stdio\n\n## 1. stdio to SSE/StreamableHTTP\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--\u003e |stdio| B[\"mcp-proxy\"]\n B \u003c--\u003e |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 passing the URL to the MCP Server SSE endpoint as the first argument to the program.\n\nArguments\n\n| Name | Required | Description | Example |\n|------------------|----------|--------------------------------------------------|-----------------------------------------------|\n| `command_or_url` | Yes | The MCP server SSE endpoint to connect to | http://example.io/sse |\n| `--headers` | No | Headers to use for the MCP server SSE connection | Authorization 'Bearer my-secret-access-token' |\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\u003e'` | 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://example.io/sse\"\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--\u003e|SSE| B[\"mcp-proxy\"]\n B \u003c--\u003e|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 | FOO=BAR |\n| `--cwd` | No | The working directory to pass to the MCP stdio server process. | /tmp |\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-cors \"\\*\" |\n| `--stateless` | No | Enable stateless mode for streamable http transports. Default is False | --no-stateless |\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\nThis will start an MCP server that can be connected to at `http://127.0.0.1:8080/sse` via SSE, or\n`http://127.0.0.1:8080/mcp/` via StreamableHttp\n\n## Installation\n\n### Installing via Smithery\n\nTo install MCP Proxy for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-proxy):\n\n```bash\nnpx -y @smithery/cli install mcp-proxy --client claude\n```\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://github.com/sparfenyuk/mcp-proxy\n```\n\n\u003e [!NOTE]\n\u003e If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.\n\n\u003e [!NOTE]\n\u003e 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:\n\n```bash\ndocker run -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --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`where 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\": \"/full/path/to/bin/mcp-proxy\",\n \"args\": [\n \"http://localhost:8932/sse\"\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/sparfenyuk/mcp-proxy:latest\n\n# Install the 'uv' package\nRUN python3 -m ensurepip \u0026\u0026 pip install --no-cache-dir uv\n\nENV PATH=\"/usr/local/bin:$PATH\" \\\n UV_PYTHON_PREFERENCE=only-system\n\nENTRYPOINT [ \"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\u003e [!NOTE]\n\u003e Don't forget to set `--pass-environment` argument, otherwise you'll end up with the error \"No interpreter found in\n\u003e managed installations or search path\"\n\n## Command line arguments\n\n```bash\nusage: mcp-proxy [-h] [-H KEY VALUE] [-e KEY VALUE] [--cwd CWD] [--pass-environment | --no-pass-environment] [--debug | --no-debug] [--port PORT]\n [--host HOST] [--stateless | --no-stateless] [--sse-port SSE_PORT] [--sse-host SSE_HOST]\n [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]\n [command_or_url] [args ...]\n\nStart the MCP proxy in one of two possible modes: as an SSE or stdio client.\n\npositional arguments:\n command_or_url Command or URL to connect to. When a URL, will run an SSE client, otherwise will run the given command and connect as a stdio client. See corresponding options for more details.\n\noptions:\n -h, --help show this help message and exit\n\nSSE client options:\n -H, --headers KEY VALUE\n Headers to pass to the SSE server. Can be used multiple times.\n\nstdio client options:\n args Any extra arguments to the command to spawn the server\n -e, --env KEY VALUE Environment variables used when spawning the server. Can be used multiple times.\n --cwd CWD The working directory to use when spawning the process.\n --pass-environment, --no-pass-environment\n Pass through all environment variables when spawning the server.\n --debug, --no-debug Enable debug mode with detailed logging output.\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\nExamples:\n mcp-proxy http://localhost:8080/sse\n mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse\n mcp-proxy --port 8080 -- your-command --arg1 value1 --arg2 value2\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```\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://modelcontextprotocol.io/docs/tools/inspector) 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 \u0026\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://127.0.0.1:8080/sse\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparfenyuk%2Fmcp-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparfenyuk%2Fmcp-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparfenyuk%2Fmcp-proxy/lists"}