Glama
Sign In

MCP Proxy Server

by sparfenyuk
GitHub
Python
MIT License
212
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

  • Provides code coverage reporting for the mcp-proxy project as indicated by the codecov badge at the top of the README.

  • Supports running and extending the proxy as a Docker container, with instructions for creating custom Docker images and Docker Compose setup.

  • Allows installation of the proxy via GitHub repository and displays GitHub license information through a badge.

mcp-proxy

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.

1.1 Configuration

This mode requires passing the URL to the MCP Server SSE endpoint as the first argument to the program.

Arguments

NameRequiredDescriptionExample
command_or_urlYesThe MCP server SSE endpoint to connect tohttp://example.io/sse
--headersNoHeaders to use for the MCP server SSE connectionAuthorization 'Bearer my-secret-access-token'

Environment Variables

NameRequiredDescriptionExample
API_ACCESS_TOKENNoCan 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:

{ "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.

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

NameRequiredDescriptionExample
command_or_urlYesThe command to spawn the MCP stdio serveruvx mcp-server-fetch
--sse-portNo, random availableThe SSE server port to listen on8080
--sse-hostNo, 127.0.0.1 by defaultThe host IP address that the SSE server will listen on0.0.0.0
--envNoAdditional environment variables to pass to the MCP stdio serverFOO=BAR
--pass-environmentNoPass through all environment variables when spawning the server--no-pass-environment
--allow-originNoPass 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:

# 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:

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:

# 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:

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:

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:

# 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:

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

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 to test the target server.

# 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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

Enables interaction with remote MCP servers using SSE transport instead of STDIO for enhanced communication capabilities.

  1. About
    1. 1. stdio to SSE
      1. 1.1 Configuration
      2. 1.2 Example usage
    2. 2. SSE to stdio
      1. 2.1 Configuration
      2. 2.2 Example usage
    3. Installation
      1. Installing via Smithery
      2. Installing via PyPI
      3. Installing via Github repository (latest)
      4. Installing as container
    4. Extending the container image
      1. Docker Compose Setup
        1. Command line arguments
          1. Testing

            Related Resources