README.md•7.27 kB
# 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:**
```bash
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:
```bash
# 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:
```bash
# 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
```bash
docker build -t mcp-proxy .
```
#### Step 2: Run the Container
**Option A: Using environment variables directly**
```bash
# 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**
```bash
# 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**
```bash
# 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
```bash
# 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
```bash
# 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.
```json
{
"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)
```bash
# Test the SSE endpoint
curl http://localhost:8000/sse/
# Check server health
curl http://localhost:8000/
```
### Testing HTTP Transport (Port 8001)
```bash
# Test the HTTP endpoint
curl http://localhost:8001/
# Check server health
curl http://localhost:8001/
```
### Testing with Different Services
```bash
# 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 `servers.json` as a volume** 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:
```bash
# 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.