297 lines
11 KiB
Markdown
297 lines
11 KiB
Markdown
# 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)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [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
|
|
```
|
|
|
|
### Troubleshooting
|
|
|
|
- **Problem**: Claude Desktop can't start the server: ENOENT code in the logs
|
|
|
|
**Solution**: Try to use the full path to the binary. To do so, open a terminal and run the command `where mcp-proxy` (macOS, Linux) or `where.exe mcp-proxy` (Windows). Then, use the output path as a value for 'command' attribute:
|
|
```json
|
|
"fetch": {
|
|
"command": "/full/path/to/bin/mcp-proxy",
|
|
"args": [
|
|
"http://localhost:8932/sse"
|
|
]
|
|
}
|
|
```
|
|
|
|
## 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.
|
|
--debug, --no-debug Enable debug mode with detailed logging output.
|
|
|
|
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
|
|
```
|