MCP Router

An intelligent MCP (Model Context Protocol) router that routes requests to child MCP servers using advanced tool selection strategies. This server acts as a smart proxy, optimizing context length and reducing LLM confusion by selectively exposing only the most relevant tools based on the current context.

Quick Start

The simplest way to use mcp-router is with uvx:

# Run with automatic setup (recommended)
uvx mcp-router

# Or with custom configuration
uvx mcp-router --config my-config.yaml --mcp-servers-json my-servers.json

# Or with web UI enabled
uvx mcp-router --web-ui

That's it! uvx mcp-router will automatically:

Install all dependencies
Detect and setup container runtime (Docker or Apple Container Framework)
Start Qdrant vector database
Auto-detect existing Claude Desktop configurations
Start the meta-mcp server with web UI at http://localhost:8080

Features

Intelligent Tool Selection

Vector Search: Fast semantic similarity using embeddings
LLM Selection: AI-powered tool selection using local LLMs
RAG-Based Selection: Context-augmented selection using retrieved documentation

Automatic Setup

Container Runtime Detection: Automatically uses Apple Container Framework on macOS or Docker
Dependency Management: Handles all Python dependencies and model downloads
Configuration Discovery: Auto-detects existing MCP server configurations
Infrastructure Setup: Starts Qdrant and other required services automatically

Web Management Interface

Real-time server monitoring and logs
Interactive configuration editor
Tool usage analytics and metrics
Child server status monitoring

Production Ready

Comprehensive logging and error handling
Performance monitoring and caching
Hot-reload configuration support
Docker deployment ready

Configuration

Auto-Detection

MCP Router automatically looks for configuration files in these locations:

Main Config (meta-server.yaml):

./config/meta-server.yaml
./meta-server.yaml
~/.meta-mcp/config.yaml
/etc/meta-mcp/config.yaml

MCP Servers Config (JSON):

./mcp-servers.json
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
~/.config/claude/claude_desktop_config.json (Linux/Windows)

Manual Configuration

If you want to customize the setup, you can provide specific paths:

uvx mcp-router --config path/to/config.yaml --mcp-servers-json path/to/servers.json

Creating Custom Config

Create a mcp-servers.json file with your child servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/files"]
    },
    "github": {
      "command": "uvx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

For advanced configuration, create a meta-server.yaml:

strategy:
  primary: "vector"      # vector, llm, or rag
  fallback: "vector"     # fallback strategy
  vector_threshold: 0.75 # similarity threshold
  max_tools: 10         # max tools to return

server:
  host: "localhost"
  port: 3456

web_ui:
  enabled: true
  port: 8080

embeddings:
  # Primary: LM Studio (optional)
  lm_studio_endpoint: "http://localhost:1234/v1/embeddings"
  lm_studio_model: "nomic-embed-text-v1.5"

  # Fallback: Local model (automatic)
  fallback_model: "all-MiniLM-L6-v2"

Command Options

uvx mcp-router [OPTIONS]

Options:
  --config PATH              Path to configuration file (auto-detected)
  --mcp-servers-json PATH    Path to MCP servers JSON (auto-detected)
  --web-ui / --no-web-ui     Enable web UI (default: enabled)
  --host TEXT                Server host
  --port INTEGER             Server port
  --log-level TEXT           Log level (DEBUG, INFO, WARNING, ERROR)
  --setup / --no-setup       Auto-setup infrastructure (default: enabled)
  --help                     Show this message and exit

Advanced Usage

Development Mode

For development with the project locally:

# Clone and use development version
git clone <repository-url>
cd mcp-router

# Install dependencies
uv sync --extra web --extra dev

# Run with development tools
uv run mcp-router start --log-level DEBUG --web-ui

Legacy Commands

The following commands are still available for advanced users:

uvx mcp-router run [OPTIONS]           # Original run command
uvx mcp-router validate-config FILE    # Validate configuration
uvx mcp-router health [OPTIONS]        # System health check
uvx mcp-router init-config [OPTIONS]   # Create example config

Tool Selection Strategies

1. Vector Search Strategy (Default)

Fast semantic similarity using embeddings
Suitable for most use cases
~50ms response time

2. LLM Selection Strategy

AI-powered context-aware selection
Best for complex queries
Requires LM Studio (optional)
~200-500ms response time

3. RAG-Based Strategy

Documentation-enhanced selection
Highest accuracy with good docs
~100-200ms response time

Integration with Claude Code

MCP Router can automatically configure itself for Claude Code:

Run uvx mcp-router once to start the server
The server will create the necessary Claude Code configuration
Restart Claude Code
MCP Router will be available as an MCP server

The configuration is automatically added to:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux/Windows: ~/.config/claude/claude_desktop_config.json

Web Interface

Access the web interface at http://localhost:8080 to:

Monitor server status and performance
View real-time logs and metrics
Manage child server configurations
Explore available tools and their usage
Test tool selection strategies

Prerequisites

MCP Router handles most dependencies automatically, but you'll need:

Python 3.11+: For running the server
Container Runtime: Docker or Apple Container Framework (auto-configured)
uvx: For package management (pip install uvx or pipx install uv)

Optional for enhanced features:

LM Studio: For custom embeddings and LLM selection
Git: For cloning and development

Troubleshooting

Common Issues

Q: "uvx not found" error

# Install uvx/uv
pip install uv
# or
pipx install uv

Q: Container runtime errors

macOS: The tool will automatically try to set up Apple Container Framework
Other systems: Install Docker and ensure it's running
Use --no-setup to skip automatic setup if needed

Q: Qdrant connection failed

# Check if Qdrant is running
curl http://localhost:6333/collections

# Restart with setup
uvx mcp-router --setup

Q: No MCP servers found

Create a mcp-servers.json file in your current directory
Or point to an existing Claude Desktop config with --mcp-servers-json

Q: Web UI not accessible

Check if port 8080 is available: lsof -i :8080
Try a different port: uvx mcp-router --port 8081

Q: Permission denied errors

# Make sure you have write permissions in the current directory
# Or run from a directory where you have write access
cd ~/my-mcp-router-workspace
uvx mcp-router

Debug Mode

For detailed troubleshooting:

uvx mcp-router --log-level DEBUG --web-ui

Check logs at ./logs/meta-server.log for detailed error information.

Architecture

MCP Router consists of:

Server Core: Main MCP server handling client connections
Tool Router: Implements intelligent tool selection strategies
Child Server Manager: Manages lifecycle of child MCP servers
Vector Store: Qdrant-based embedding storage and similarity search
Web Interface: Real-time monitoring and configuration dashboard
Auto-Setup: Infrastructure detection and configuration

Security Considerations

Run child servers with minimal privileges
Use environment variables for sensitive configuration
Review child server configurations before use
Monitor logs for unusual activity
Keep dependencies updated with uvx auto-updates

Contributing

Fork the repository

Clone your fork and set up development environment:

git clone https://github.com/yourusername/meta-mcp.git
cd meta-mcp
uv sync --dev  # Install dependencies
uv run pre-commit install  # Set up pre-commit hooks

Create a feature branch:

git checkout -b feature/amazing-feature

Make your changes with tests. Pre-commit hooks will automatically:
- Format code with Ruff
- Lint and fix issues
- Check type annotations with mypy
- Validate YAML/JSON files

Run all quality checks manually:

./scripts/check-all.sh
# Or individually:
uv run ruff format src/ tests/
uv run ruff check src/ tests/ --fix
uv run mypy src/
uv run pytest

Run tests manually when needed:

uv run pre-commit run pytest --hook-stage manual

Submit a pull request with a clear description of changes

Development Setup

# Clone your fork
git clone https://github.com/yourusername/meta-mcp.git
cd meta-mcp

# Install dependencies
uv sync --extra dev --extra web

# Run tests
uv run pytest

# Run the development version
uv run mcp-router start --log-level DEBUG

Publishing

This project uses GitHub Actions for automated publishing to PyPI. To create a new release:

Create a new tag: git tag v0.1.1
Push the tag: git push origin v0.1.1
GitHub Actions will automatically build and publish to PyPI

License

MIT License - see LICENSE file for details.

Meta MCP Server