Skip to main content
Glama

mcp-proxy

by sokunmin
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

FastMCP Proxy Server

This project provides a simple and flexible proxy server built with FastMCP. It is designed to expose one or more underlying MCP (Model Context Protocol) servers over various transport protocols, making them accessible to a wider range of clients.

The server is containerized using Docker for easy and consistent deployment, optimized for production environments.

Features

  • Multiple Transports: Expose MCP servers over stdio, sse (Server-Sent Events), or http.

  • Flexible Configuration: Easily configure which MCP servers to proxy by editing the servers.json file.

  • Lightweight & Fast: Built on the efficient FastMCP library and runs in a small Alpine Linux container.

  • Production Ready: Optimized Docker configuration for production deployment.

  • MCP Server Support: Supports both Node.js (npx) and Python (uvx) based MCP servers.

Requirements

  • Docker and Docker Compose

How to Run

This project is designed for production deployment using Docker. You can run it using either Docker Compose or direct Docker commands:

Prerequisites

  1. Clone the repository:

    git clone https://github.com/sokunmin/mcp-proxy.git cd mcp-proxy

Method 1: Using Docker Compose (Recommended)

The easiest way to run the proxy with predefined configuration:

# Run with default settings (SSE transport, port 8000) docker-compose up --build # Run in background docker-compose up -d --build # Stop the service docker-compose down

Override Environment Variables

You can override the default transport without editing files:

# Run with HTTP transport TRANSPORT=http PORT=8001 docker-compose up # Run with custom port PORT=9000 docker-compose up # Run with multiple overrides TRANSPORT=http PORT=8080 docker-compose up

Method 2: Using Docker Run

For more control over the container configuration:

Step 1: Build the Image

docker build -t mcp-proxy .

Step 2: Run the Container

Option A: Using environment variables directly

# SSE Transport (Default) docker run -d --name mcp-proxy \ -p 8000:8000 \ -e TRANSPORT=sse \ -e HOST=0.0.0.0 \ -e PORT=8000 \ -e TZ=Etc/UTC \ mcp-proxy # HTTP Transport docker run -d --name mcp-proxy-http \ -p 8001:8001 \ -e TRANSPORT=http \ -e HOST=0.0.0.0 \ -e PORT=8001 \ -e TZ=Etc/UTC \ mcp-proxy

Option B: Using .env file with consistent PORT variable

# Load environment variables from .env file source .env # Run with loaded variables docker run -d --name mcp-proxy \ -p ${PORT}:${PORT} \ -e TRANSPORT=${TRANSPORT} \ -e HOST=${HOST} \ -e PORT=${PORT} \ -e TZ=${TZ} \ mcp-proxy # For HTTP transport, override specific variables TRANSPORT=http PORT=8001 docker run -d --name mcp-proxy-http \ -p ${PORT}:${PORT} \ -e TRANSPORT=${TRANSPORT} \ -e HOST=${HOST} \ -e PORT=${PORT} \ -e TZ=${TZ} \ mcp-proxy

Option C: Using --env-file

# Use .env file directly docker run -d --name mcp-proxy \ --env-file .env \ -p 8000:8000 \ mcp-proxy # Override specific variables docker run -d --name mcp-proxy-http \ --env-file .env \ -e TRANSPORT=http \ -e PORT=8001 \ -p 8001:8001 \ mcp-proxy

Container Management

# View logs docker logs mcp-proxy # Stop the container docker stop mcp-proxy # Remove the container docker rm mcp-proxy # View running containers docker ps

Environment Variables

The following environment variables can be configured in the .env file or passed directly:

  • TRANSPORT: Transport protocol (sse, http, stdio) - Default: sse

  • HOST: Host to bind to - Default: 0.0.0.0

  • PORT: Port number for the service - Default: 8000

  • TZ: Timezone - Default: Etc/UTC

Quick Start Examples

# Default SSE on port 8000 docker-compose up # HTTP on port 8001 TRANSPORT=http PORT=8001 docker-compose up # Custom port PORT=9000 docker-compose up # Run in background docker-compose up -d

Configuration

To configure the proxy, edit the servers.json file. You can add, remove, or modify the MCP servers that you want to expose.

{ "mcpServers": { "context7": { "transport": "stdio", "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "time": { "transport": "stdio", "command": "uvx", "args": ["mcp-server-time", "--local-timezone", "Etc/UTC"] } } }

The servers.json file is mounted as a volume, so changes take effect on container restart.

How to Test

You can test the running proxy using any MCP-compliant client or a tool like curl.

Testing SSE Transport (Port 8000)

# Test the SSE endpoint curl http://localhost:8000/sse/ # Check server health curl http://localhost:8000/

Testing HTTP Transport (Port 8001)

# Test the HTTP endpoint curl http://localhost:8001/ # Check server health curl http://localhost:8001/

Testing with Different Services

# Test SSE service docker-compose up mcp-proxy-sse curl http://localhost:8000/sse/ # Test HTTP service docker-compose up mcp-proxy-http curl http://localhost:8001/

Testing MCP Servers

The proxy currently supports these MCP servers:

  • context7: Document search and context retrieval (Node.js via npx)

  • fetch: Web content fetching (Python via uvx)

  • time: Time and timezone operations (Python via uvx)

All servers are automatically started by the proxy when needed.

Production Deployment

Docker Configuration Details

  • Base Image: ghcr.io/astral-sh/uv:python3.12-alpine

  • Optimized: Small size, production-ready

  • Security: Runs as non-root user

  • Environment: Configurable via environment variables

Best Practices

  1. Use environment variables for configuration instead of modifying files

  2. Mount for easy configuration updates

  3. Use Docker Compose for consistent deployment

  4. Monitor logs using docker-compose logs -f

  5. Use health checks to ensure service availability

Scaling

For high-availability deployment, consider:

  • Using multiple replicas behind a load balancer

  • Implementing proper logging and monitoring

  • Using container orchestration (Kubernetes, Docker Swarm)

Troubleshooting

Common Issues

  1. Port conflicts: Make sure ports 8000/8001 are not in use by other applications

  2. Container build issues: Use docker-compose down and docker-compose up --build to force a clean rebuild

  3. Configuration errors: Check servers.json syntax and ensure all required fields are present

Monitoring

Check service health:

# View logs docker-compose logs -f mcp-proxy-sse # Check container status docker-compose ps # Access container shell (if needed) docker-compose exec mcp-proxy-sse sh

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss any changes.

For development setup, please use the dev branch which includes development-optimized configurations.

Deploy Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

hybrid server

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

Tools

mcp proxy

  1. Features
    1. Requirements
      1. How to Run
        1. Prerequisites
        2. Method 1: Using Docker Compose (Recommended)
        3. Method 2: Using Docker Run
        4. Environment Variables
        5. Quick Start Examples
      2. Configuration
        1. How to Test
          1. Testing SSE Transport (Port 8000)
          2. Testing HTTP Transport (Port 8001)
          3. Testing with Different Services
          4. Testing MCP Servers
        2. Production Deployment
          1. Docker Configuration Details
          2. Best Practices
          3. Scaling
        3. Troubleshooting
          1. Common Issues
          2. Monitoring
        4. Contributing

          Related Resources

          Related MCP Servers

          • mcprouter

            chatmcp
            -
            security
            A
            license
            -
            quality
            A proxy service that connects MCP clients to remote MCP servers, allowing users to use server keys from MCP.so to access remote resources without running their own server.
            Last updated -
            20
            3
            MIT License
            • Apple

          • Atrax

            metcalfc
            -
            security
            F
            license
            -
            quality
            Proxy that aggregates multiple MCP servers and presents them as a unified interface, allowing clients to access resources from multiple servers transparently.
            Last updated -
            5

          • modbus-mcp

            kukapay
            -
            security
            A
            license
            -
            quality
            modbus-mcp
            Last updated -
            18
            MIT License
            • Linux
            • Apple

          View all related MCP servers

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/sokunmin/mcp-proxy'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server