MCP Router

MCP Router Demo

MCP Router is a Python-based unified gateway for multiple Model Context Protocol (MCP) servers. It provides a web interface for managing servers, intelligent routing with hierarchical tool discovery, and sandboxed execution environments for any programming language.

🚀 Quick Start

# Clone the repository
git clone https://github.com/locomotive-agency/mcp-router.git
cd mcp-router

# Run the setup script (installs Docker and sets up the project)
chmod +x setup.sh
./setup.sh

# Edit configuration
nano .env  # Add your ANTHROPIC_API_KEY and set ADMIN_PASSCODE

# Start the web interface
source venv/bin/activate
python -m mcp_router.web

# Open in browser
open http://localhost:8000

🎯 Key Features

Core Functionality

Unified MCP Gateway: Single interface for multiple MCP servers
Web Management UI: Flask-based interface with real-time updates via htmx
Intelligent Routing: Hierarchical tool discovery prevents tool overload
Language Agnostic: Support for any programming language via sandboxed containers
Built-in Python Sandbox: Data science environment with popular libraries
Authentication: Passcode-protected admin interface for secure remote hosting

Server Management

GitHub Integration: Automatic MCP server detection and configuration from repos
Claude Analysis: AI-powered extraction of server requirements
Container Sandboxing: Secure isolation using Docker (npx, uvx, or custom images)
Real-time Control: Start/stop servers with live log streaming
Persistent Storage: SQLite database for configurations

Transport & Integration

Multiple Transports: stdio (local) and HTTP (remote) with authentication
Claude Desktop Ready: Direct integration with Anthropic's desktop app
API Authentication: Secure access with API keys for remote connections
Auto-discovery: Dynamic server and tool discovery without restarts

📋 Prerequisites

Python 3.11+ - Core runtime
Docker - Required for sandboxed execution
Git - For cloning repositories
Anthropic API Key - For Claude repository analysis (optional but recommended)

🛠️ Installation

Option 1: Automated Setup (Recommended)

We provide a setup script that handles Docker installation and project setup:

chmod +x setup.sh
./setup.sh

The script will:

Install Docker (Ubuntu/Debian, Fedora, macOS)
Verify Python 3.11+ is installed
Create a virtual environment
Install project dependencies
Set up configuration files
Create necessary directories

Option 2: Manual Setup

Install Docker
- Ubuntu/Debian: Follow Docker's official guide
- macOS: Install Docker Desktop
- Other: See Docker installation docs

Clone and Install

git clone https://github.com/locomotive-agency/mcp-router.git
cd mcp-router

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install package
pip install -e .

# Create data directory
mkdir -p data

# Copy environment template
cp env.example .env

Configure Environment Edit .env file with your settings:

# Required for security
ADMIN_PASSCODE=your-secure-passcode-here

# Required for repository analysis
ANTHROPIC_API_KEY=your-api-key-here

# Optional customizations
MCP_PYTHON_IMAGE=python:3.11-slim
MCP_NODE_IMAGE=node:20-slim

🔐 Authentication

MCP Router includes a simple passcode-based authentication system to protect the admin interface when hosted remotely.

Setting Up Authentication

Set a strong passcode in your .env file:
```
ADMIN_PASSCODE=your-secure-passcode-here
```
- Minimum 8 characters required
- Use a strong, unique passcode
- Never use the default passcode in production!
First-time login:
- Navigate to http://localhost:8000
- You'll be redirected to the login page
- Enter your passcode
- You'll stay logged in until you explicitly log out
Security Notes:
- The passcode is hashed using bcrypt
- Sessions persist across browser restarts
- Always use HTTPS in production
- Consider additional security measures (VPN, IP restrictions) for sensitive deployments

🚦 Usage

Starting the Application

Start Web Interface
```
source venv/bin/activate
python -m mcp_router.web
```
Access at: http://localhost:8000

First time: You'll be prompted to log in with your passcode.
Add MCP Servers
- Click "Add Server" in the web UI
- Enter a GitHub repository URL
- Claude will analyze and configure automatically
- Review and save the configuration
Control MCP Server
- Navigate to "MCP Control" in the navigation bar
- Select transport mode (stdio for Claude Desktop, HTTP for remote)
- Click "Start Server" to launch
- Copy connection details for your client

Integration Examples

Claude Desktop Integration

Start MCP server in stdio mode via Control Panel

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-router": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "mcp_router.server"]
    }
  }
}

Restart Claude Desktop

Remote HTTP Access

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

# Connect to HTTP transport
async with Client(
    "http://localhost:8001/mcp/",
    auth=BearerAuth(token="your-api-key")
) as client:
    # List available providers
    providers = await client.call_tool("list_providers")
    print(f"Available servers: {providers}")
    
    # List tools from a specific provider
    tools = await client.list_tools(provider="github-mcp-server")
    
    # Call a tool
    result = await client.call_tool(
        "search_repositories",
        provider="github-mcp-server",
        query="mcp servers"
    )

Docker Compose Deployment

docker-compose up --build

Web UI: http://localhost:8000
MCP Server: http://localhost:8001/mcp/

🏗️ Architecture

System Design

┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │     │   Web Browser   │
│   (stdio)       │     │   (Admin UI)    │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │ stdio                 │ HTTP
         │                       │
┌────────┴───────────────────────┴────────┐
│           MCP Router Service            │
│  ┌─────────────┐  ┌──────────────┐     │
│  │ Flask Web   │  │ FastMCP      │     │
│  │ Interface   │  │ Proxy Router │     │
│  └─────────────┘  └──────────────┘     │
│  ┌─────────────┐  ┌──────────────┐     │
│  │   Claude    │  │  Container   │     │
│  │  Analyzer   │  │  Manager     │     │
│  └─────────────┘  └──────────────┘     │
└─────────────────────────────────────────┘
                    │
    ┌───────────────┼───────────────┐
    │               │               │
┌───▼────┐    ┌────▼────┐    ┌────▼────┐
│  NPX   │    │   UVX   │    │ Docker  │
│(Node.js)│    │(Python) │    │  (Any)  │
└────────┘    └─────────┘    └─────────┘

Hierarchical Tool Discovery

The router implements a two-step discovery pattern to prevent overwhelming LLMs:

Initial Tools: Only python_sandbox and list_providers visible
Provider Discovery: list_providers() returns available servers
Server Tools: tools/list(provider="server_name") shows server-specific tools
Tool Execution: Tools called with provider parameter for routing

This design maintains a clean, stateless architecture while providing intuitive navigation.

⚙️ Configuration

Environment Variables

Create a .env file with:

# Flask Configuration
FLASK_PORT=8000
FLASK_ENV=development
SECRET_KEY=your-secret-key-here

# Authentication (REQUIRED for security)
ADMIN_PASSCODE=your-secure-passcode-here

# Claude API (Required for GitHub analysis)
ANTHROPIC_API_KEY=sk-ant-...

# Docker Configuration
DOCKER_HOST=unix:///var/run/docker.sock  # Linux/Mac
# DOCKER_HOST=tcp://localhost:2375       # Windows

# Container Images (Optional)
MCP_PYTHON_IMAGE=python:3.11-slim  # For Python servers
MCP_NODE_IMAGE=node:20-slim        # For Node.js servers

# MCP Server Configuration (Set via UI)
MCP_TRANSPORT=http      # stdio, http, or sse
MCP_HOST=127.0.0.1
MCP_PORT=8001
MCP_PATH=/mcp
MCP_API_KEY=auto-generated-if-not-set

Supported Runtimes

Runtime	Command	Use Case	Base Image
npx	`npx @org/package`	Node.js/TypeScript servers	`node:20-slim`
uvx	`uvx package`	Python servers	`python:3.11-slim`
docker	`docker run ...`	Any language/custom setup	User specified

🧪 Development

Running Tests

source venv/bin/activate
pytest -v

Test Coverage

✅ Claude repository analyzer
✅ Middleware provider filtering
✅ Database models and operations
✅ Log level detection
✅ Web UI routes and functionality
✅ Authentication system

Project Structure

mcp-router/
├── src/mcp_router/      # Main package
│   ├── app.py          # Flask application
│   ├── auth.py         # Authentication system
│   ├── server.py       # MCP server with FastMCP
│   ├── container_manager.py  # Docker container lifecycle
│   ├── claude_analyzer.py    # GitHub repo analysis
│   ├── middleware.py   # Provider filter middleware
│   ├── models.py       # SQLAlchemy models
│   ├── server_manager.py     # MCP server processes
│   ├── templates/      # Jinja2 templates
│   └── static/         # CSS, JS assets
├── tests/              # Test suite
├── data/               # SQLite database
├── docker-compose.yml  # Container orchestration
├── setup.sh           # Automated setup script
└── .env.example       # Environment template

🚀 Performance

Optimization Strategies

Smart Image Management
- Common base images pre-pulled on startup
- Shared layers between containers
- Configurable slim images for minimal size
Container Lifecycle
- Containers reused between operations
- First run: ~5 seconds (after image pull)
- Subsequent runs: <2 seconds
Efficient Routing
- Stateless design with no session overhead
- Direct stdio communication for local clients
- Minimal middleware processing

🐛 Troubleshooting

Common Issues

Docker not running

# Linux
sudo systemctl start docker

# macOS
# Start Docker Desktop from Applications

Permission denied errors

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

NPM idealTree errors

The system automatically cleans npm cache
If persists, manually clear: docker system prune

Port already in use

# Change port in .env file
FLASK_PORT=8080
MCP_PORT=8002

Login issues

Ensure ADMIN_PASSCODE is set in .env
Minimum 8 characters required
Clear browser cookies if having persistent issues

🤝 Contributing

This is an MVP project with a focused 4-week timeline. Contributions should align with the roadmap in project.md.

Development Priorities

Core functionality and stability
Test coverage and documentation
Performance optimizations
Additional transport implementations

📄 License

[License information to be added]

🙏 Acknowledgments

Built with FastMCP for MCP protocol implementation
UI powered by htmx for seamless interactions
Container sandboxing via llm-sandbox