Proxy MCP Server

Overview

MCP Proxy is a versatile tool that bridges different Model Context Protocol (MCP) transport mechanisms. It solves the compatibility problem between MCP servers that use stdio and clients that expect HTTP/SSE connections, or vice versa.

The proxy operates in two primary modes:

1. stdio to SSE/StreamableHttp: Converts a stdio-based MCP server into an HTTP/SSE endpoint
2. SSE to stdio: Converts an HTTP/SSE MCP server into a stdio interface

Installation Options

Via PyPI

pip install mcp-proxy

Via GitHub (Latest Version)

pip install git+https://github.com/sparfenyuk/mcp-proxy.git

Via Container

docker pull ghcr.io/sparfenyuk/mcp-proxy:latest

Usage Examples

Mode 1: stdio to SSE/StreamableHttp

This mode allows you to expose a stdio-based MCP server as an HTTP endpoint:

mcp-proxy stdio-to-sse --command "python -m your_mcp_server" --port 8000

Configuration Options:

• --command: The command to start your stdio MCP server
• --port: HTTP port to listen on (default: 8000)
• --host: Host to bind to (default: 127.0.0.1)
• --env: Environment variables to pass to the MCP server
• --cwd: Working directory for the MCP server
• --stateless: Run in stateless mode (no session persistence)
• --debug: Enable verbose logging

Mode 2: SSE to stdio

This mode connects to an HTTP/SSE MCP server and exposes it as a stdio interface:

mcp-proxy sse-to-stdio --url http://localhost:8000

Configuration Options:

• --url: URL of the HTTP/SSE MCP server
• --debug: Enable verbose logging

Advanced Configuration

Environment Variables

You can pass environment variables to the underlying MCP server:

mcp-proxy stdio-to-sse --command "python -m your_server" --env "API_KEY SECRET_TOKEN"

Working Directory

Specify a custom working directory for the MCP server:

mcp-proxy stdio-to-sse --command "python -m your_server" --cwd "/path/to/directory"

Docker Compose Setup

For containerized deployments, you can use Docker Compose:

version: '3'
services:
  mcp-proxy:
    image: ghcr.io/sparfenyuk/mcp-proxy:latest
    ports:
      - "8000:8000"
    command: stdio-to-sse --command "python -m your_server" --host 0.0.0.0 --port 8000
    volumes:
      - ./your_server:/app/your_server

Extending the Container Image

You can create a custom Docker image that includes both mcp-proxy and your MCP server:

FROM ghcr.io/sparfenyuk/mcp-proxy:latest

# Install your MCP server
COPY your_server /app/your_server
RUN pip install -r /app/your_server/requirements.txt

# Configure the proxy to run your server
ENTRYPOINT ["mcp-proxy", "stdio-to-sse", "--command", "python -m your_server", "--host", "0.0.0.0"]

Troubleshooting

If you encounter issues:

1. Enable debug mode with --debug to see detailed logs
2. Verify that your MCP server is working correctly on its own
3. Check network connectivity if using remote servers
4. Ensure proper permissions for any file operations

For more information and updates, visit the GitHub repository.