Meta Mcp

Meta MCP

[](https://github.com/anirudhlath/meta-mcp/actions/workflows/ci.yml)

An intelligent MCP (Model Context Protocol) router that routes requests to child MCP servers using advanced tool selection strategies. Meta MCP 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

Run Meta MCP straight from this repository with uvx:

# Run with automatic setup (recommended)
uvx --from git+https://github.com/anirudhlath/meta-mcp meta-mcp

# Or with custom configuration
uvx --from git+https://github.com/anirudhlath/meta-mcp meta-mcp \
    --config my-config.yaml --mcp-servers-json my-servers.json

# Or install it as a persistent CLI tool
uv tool install git+https://github.com/anirudhlath/meta-mcp
meta-mcp

On startup, meta-mcp will automatically:

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

Architecture

flowchart TD
    subgraph Server["Meta MCP server"]
        Engine["Routing engine(primary strategy + fallback)"]
        Vector["Vector search router"]
        LLM["LLM router"]
        RAG["RAG router"]
        Pipeline["RAG pipeline(doc chunking + retrieval)"]
        Emb["Embedding service"]
        Manager["Child server manager"]
        Engine --> Vector
        Engine --> LLM
        Engine --> RAG
        RAG --> Pipeline
        Vector --> Emb
        Pipeline --> Emb
        Engine -->|selected tools / proxied calls| Manager
    end

    Client["MCP client(Claude Desktop / Claude Code)"] -->|MCP protocol| Engine

    Vector --> Qdrant[("Qdranttool + doc embeddings")]
    Pipeline --> Qdrant
    Emb -->|primary| LMS["LM Studioembeddings + local LLM"]
    Emb -.->|fallback| ST["sentence-transformers(local model)"]
    LLM --> LMS
    Pipeline --> LMS

    Manager --> C1["Child MCP server(e.g. filesystem)"]
    Manager --> C2["Child MCP server(e.g. github)"]
    Manager --> C3["Child MCP server(...)"]

Main components (all under src/meta_mcp/):

• Server core (server/meta_server.py): main MCP server handling client connections; its routing engine applies the configured primary strategy with automatic fallback
• Routing strategies (routing/): vector search (vector_router.py), LLM selection (llm_router.py), and RAG-based selection (rag_router.py)
• RAG pipeline (rag/pipeline.py): chunks and indexes child-server documentation, retrieves relevant context, and augments selection queries
• Embedding service (embeddings/service.py): LM Studio embeddings when available, with automatic sentence-transformers fallback and local caching
• Vector store (vector_store/qdrant_client.py): Qdrant-based storage and similarity search for tool and documentation embeddings
• Child server manager (child_servers/): spawns and manages the lifecycle of downstream MCP servers and proxies tool calls to them
• Web interface (web_ui/): real-time monitoring and configuration dashboard
• Auto-setup (health/): infrastructure detection, health checks, and automatic configuration

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

Operations

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

Configuration

Auto-Detection

Meta MCP 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 --from git+https://github.com/anirudhlath/meta-mcp meta-mcp \
    --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": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@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

meta-mcp [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

Additional subcommands are available for advanced use:

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

(When running via uvx, prefix these with uvx --from git+https://github.com/anirudhlath/meta-mcp.)

Tool Selection Strategies

1. Vector Search Strategy (Default)

• Fast semantic similarity using embeddings
• Suitable for most use cases

2. LLM Selection Strategy

• AI-powered context-aware selection
• Best for complex queries
• Requires LM Studio (optional)

3. RAG-Based Strategy

• Documentation-enhanced selection
• Highest accuracy with good docs

Integration with Claude Code

Meta MCP can automatically configure itself for Claude Code:

1. Run uvx --from git+https://github.com/anirudhlath/meta-mcp meta-mcp once to start the server
2. The server will create the necessary Claude Code configuration
3. Restart Claude Code
4. Meta MCP 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

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

• Python 3.11+: For running the server
• Container Runtime: Docker or Apple Container Framework (auto-configured)
• uv: For package management (installation guide)

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 uv (which provides uvx) following the official installation guide.

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 --from git+https://github.com/anirudhlath/meta-mcp meta-mcp --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 with --port 8081

Q: Permission denied errors

• Make sure you have write permissions in the current directory (Meta MCP writes logs and caches there)
• Or run from a directory where you have write access

Debug Mode

For detailed troubleshooting:

uvx --from git+https://github.com/anirudhlath/meta-mcp meta-mcp --log-level DEBUG --web-ui

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

Development

# Clone the repository
git clone https://github.com/anirudhlath/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 meta-mcp start --log-level DEBUG --web-ui

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

Contributing

1. Fork the repository
2. Clone your fork and set up the development environment:

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

1. Create a feature branch:

``bash git checkout -b feature/amazing-feature ``

1. 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

1. Run all quality checks:

``bash ./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 ``

1. Submit a pull request with a clear description of changes

License

MIT License - see [LICENSE](LICENSE) file for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anirudhlath
• Source: anirudhlath/meta-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.