# Meta Mcp

> Intelligent MCP (Model Context Protocol) router that selects tools via embeddings, semantic search, and RAG over a Qdrant vector database. Python · FastAPI · Qdrant · Docker.

- **Type:** MCP server
- **Install:** `agentstack add mcp-anirudhlath-meta-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [anirudhlath](https://agentstack.voostack.com/s/anirudhlath)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [anirudhlath](https://github.com/anirudhlath)
- **Source:** https://github.com/anirudhlath/meta-mcp

## Install

```sh
agentstack add mcp-anirudhlath-meta-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`:

```bash
# 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

```mermaid
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:

```bash
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:

```json
{
  "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`:

```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

```bash
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:

```bash
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](https://docs.astral.sh/uv/getting-started/installation/))

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](https://docs.astral.sh/uv/getting-started/installation/).

**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**
```bash
# 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:

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

```bash
# 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
   ```

3. Create a feature branch:
   ```bash
   git checkout -b feature/amazing-feature
   ```

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

5. 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
   ```

6. 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](https://github.com/anirudhlath)
- **Source:** [anirudhlath/meta-mcp](https://github.com/anirudhlath/meta-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-anirudhlath-meta-mcp
- Seller: https://agentstack.voostack.com/s/anirudhlath
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.