Content
# mcp-proxy
[](https://codecov.io/gh/sparfenyuk/mcp-proxy)
[](https://smithery.ai/server/mcp-proxy)
- [mcp-proxy](#mcp-proxy)
- [About](#about)
- [1. stdio to SSE](#1-stdio-to-sse)
- [1.1 Configuration](#11-configuration)
- [1.2 Example usage](#12-example-usage)
- [2. SSE to stdio](#2-sse-to-stdio)
- [2.1 Configuration](#21-configuration)
- [2.2 Example usage](#22-example-usage)
- [Installation](#installation)
- [Installing via Smithery](#installing-via-smithery)
- [Installing via PyPI](#installing-via-pypi)
- [Installing via Github repository (latest)](#installing-via-github-repository-latest)
- [Installing as container](#installing-as-container)
- [Extending the container image](#extending-the-container-image)
- [Docker Compose Setup](#docker-compose-setup)
- [Command line arguments](#command-line-arguments)
- [Testing](#testing)
## About
The `mcp-proxy` is a tool that lets you switch between server transports. There are two supported modes:
1. stdio to SSE
2. SSE to stdio
## 1. stdio to SSE
Run a proxy server from stdio that connects to a remote SSE server.
This mode allows clients like Claude Desktop to communicate to a remote server over SSE even though it is not supported natively.
```mermaid
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
```
### 1.1 Configuration
This mode requires passing the URL to the MCP Server SSE endpoint as the first argument to the program.
Arguments
| Name | Required | Description | Example |
| ---------------- | -------- | ------------------------------------------------ | --------------------------------------------- |
| `command_or_url` | Yes | The MCP server SSE endpoint to connect to | http://example.io/sse |
| `--headers` | No | Headers to use for the MCP server SSE connection | Authorization 'Bearer my-secret-access-token' |
Environment Variables
| Name | Required | Description | Example |
| ------------------ | -------- | ---------------------------------------------------------------------------- | ---------- |
| `API_ACCESS_TOKEN` | No | Can be used instead of `--headers Authorization 'Bearer <API_ACCESS_TOKEN>'` | YOUR_TOKEN |
### 1.2 Example usage
`mcp-proxy` is supposed to be started by the MCP Client, so the configuration must be done accordingly.
For Claude Desktop, the configuration entry can look like this:
```json
{
"mcpServers": {
"mcp-proxy": {
"command": "mcp-proxy",
"args": ["http://example.io/sse"],
"env": {
"API_ACCESS_TOKEN": "access-token"
}
}
}
}
```
## 2. SSE to stdio
Run a proxy server exposing a SSE server that connects to a local stdio server.
This allows remote connections to the local stdio server. The `mcp-proxy` opens a port to listen for SSE requests, spawns a local stdio server that handles MCP requests.
```mermaid
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
```
### 2.1 Configuration
This mode requires the `--sse-port` argument to be set. The `--sse-host` argument can be set to specify the host IP address that the SSE server will listen on. Additional environment variables can be passed to the local stdio server using the `--env` argument. The command line arguments for the local stdio server must be passed after the `--` separator.
Arguments
| Name | Required | Description | Example |
| -------------------- | -------------------------- | ---------------------------------------------------------------- | --------------------- |
| `command_or_url` | Yes | The command to spawn the MCP stdio server | uvx mcp-server-fetch |
| `--sse-port` | No, random available | The SSE server port to listen on | 8080 |
| `--sse-host` | No, `127.0.0.1` by default | The host IP address that the SSE server will listen on | 0.0.0.0 |
| `--env` | No | Additional environment variables to pass to the MCP stdio server | FOO=BAR |
| `--pass-environment` | No | Pass through all environment variables when spawning the server | --no-pass-environment |
| `--allow-origin` | No | Pass through all environment variables when spawning the server | --allow-cors "\*" |
### 2.2 Example usage
To start the `mcp-proxy` server that listens on port 8080 and connects to the local MCP server:
```bash
# Start the MCP server behind the proxy
mcp-proxy uvx mcp-server-fetch
# Start the MCP server behind the proxy with a custom port
mcp-proxy --sse-port=8080 uvx mcp-server-fetch
# Start the MCP server behind the proxy with a custom host and port
mcp-proxy --sse-host=0.0.0.0 --sse-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
mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
```
This will start an MCP server that can be connected to at `http://127.0.0.1:8080/sse`
## Installation
### Installing via Smithery
To install MCP Proxy for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-proxy):
```bash
npx -y @smithery/cli install mcp-proxy --client claude
```
### Installing via PyPI
The stable version of the package is available on the PyPI repository. You can install it using the following command:
```bash
# Option 1: With uv (recommended)
uv tool install mcp-proxy
# Option 2: With pipx (alternative)
pipx install mcp-proxy
```
Once installed, you can run the server using the `mcp-proxy` command. See configuration options for each mode above.
### Installing via Github repository (latest)
The latest version of the package can be installed from the git repository using the following command:
```bash
uv tool install git+https://github.com/sparfenyuk/mcp-proxy
```
> [!NOTE]
> If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.
> [!NOTE]
> If you want to delete the server, use the `uv tool uninstall mcp-proxy` command.
### Installing as container
Starting from version 0.3.2, it's possible to pull and run the corresponding container image:
```bash
docker run -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help
```
## Extending the container image
You can extend the `mcp-proxy` container image to include additional executables. For instance, `uv` is not included by default, but you can create a custom image with it:
```Dockerfile
# 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" ]
```
## Docker Compose Setup
With the custom Dockerfile, you can define a service in your Docker Compose file:
```yaml
services:
mcp-proxy-custom:
build:
context: .
dockerfile: mcp-proxy.Dockerfile
network_mode: host
restart: unless-stopped
ports:
- 8096:8096
command: "--pass-environment --sse-port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"
```
> [!NOTE]
> Don't forget to set `--pass-environment` argument, otherwise you'll end up with the error "No interpreter found in managed installations or search path"
## Command line arguments
```bash
usage: mcp-proxy [-h] [-H KEY VALUE] [-e KEY VALUE] [--pass-environment | --no-pass-environment] [--sse-port SSE_PORT] [--sse-host SSE_HOST]
[--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
[command_or_url] [args ...]
Start the MCP proxy in one of two possible modes: as an SSE or stdio client.
positional arguments:
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.
options:
-h, --help show this help message and exit
SSE client options:
-H KEY VALUE, --headers KEY VALUE
Headers to pass to the SSE server. Can be used multiple times.
stdio client options:
args Any extra arguments to the command to spawn the server
-e KEY VALUE, --env KEY VALUE
Environment variables used when spawning the server. Can be used multiple times.
--pass-environment, --no-pass-environment
Pass through all environment variables when spawning the server.
SSE server options:
--sse-port SSE_PORT Port to expose an SSE server on. Default is a random port
--sse-host SSE_HOST Host to expose an SSE server on. Default is 127.0.0.1
--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 --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
mcp-proxy --sse-port 8080 -- your-command --arg1 value1 --arg2 value2
mcp-proxy your-command --sse-port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
mcp-proxy your-command --sse-port 8080 --allow-origin='*'
```
## Testing
Check the `mcp-proxy` server by running it with the `mcp-server-fetch` server. You can use the [inspector tool](https://modelcontextprotocol.io/docs/tools/inspector) to test the target server.
```bash
# Run the stdio server called mcp-server-fetch behind the proxy over SSE
mcp-proxy --sse-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
```
