Meta MCP Server

Um servidor MCP para roteamento inteligente de ferramentas, utilizando um banco de dados vetorial Qdrant e LM Studio para embeddings.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Deck

Seu painel de comando para servidores MCP. MCP Deck é um roteador inteligente de MCP (Model Context Protocol): ele inicia seus servidores MCP filhos, incorpora suas ferramentas e as expõe a um cliente MCP por meio de uma única conexão — seja fazendo proxy de todas as ferramentas diretamente (com namespace) ou, por meio da meta-ferramenta find_tools, permitindo que o cliente pergunte "qual ferramenta devo usar para X?" e receba as mais relevantes em vez da lista inteira.

Há duas maneiras de executá-lo:

mcpdeck serve — um servidor MCP via stdio para Claude Desktop / Claude Code (ou qualquer cliente MCP). Esta é a integração que a maioria das pessoas deseja.
mcpdeck start — um processo independente de dashboard/roteador com interface web Gradio, útil para desenvolvimento, depuração da seleção de ferramentas e inspeção da saúde dos servidores filhos fora de um cliente MCP.

Instale via uvx/uv tool install a partir do git, como mostrado abaixo, ou, quando uma versão com tag for publicada no PyPI, uv tool install mcpdeck / uvx mcpdeck.

Pré-requisitos

Python 3.11+
uv — fornece os comandos uvx e uv usados ao longo deste README. Se você tiver apenas pipx, execute pipx install uv para obter uvx.
Docker ou Apple Container (macOS Apple Silicon) — necessário para executar o Qdrant, que dá suporte à seleção de ferramentas baseada em vetores. Opcional se você usar apenas --no-setup contra um Qdrant já em execução, ou se não precisar de roteamento de seleção de ferramentas.
LM Studio (opcional) — para embeddings locais e seleção de ferramentas baseada em LLM. Sem ele, o MCP Deck usa automaticamente um modelo sentence-transformers incluído.

Uso com Claude Desktop / Claude Code

Este é o caminho mcpdeck serve: um servidor MCP via stdio que expõe cada ferramenta filha como {server}__{tool} além de uma meta-ferramenta find_tools. stdout é reservado para o protocolo JSON-RPC — todos os logs e saídas legíveis por humanos vão para o stderr, portanto é seguro executar sob o supervisor de processos de qualquer cliente MCP.

Adicione à configuração do seu cliente MCP (claude_desktop_config.json do Claude Desktop, ou .mcp.json do Claude Code):

{
  "mcpServers": {
    "mcpdeck": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/anirudhlath/mcpdeck",
        "mcpdeck",
        "serve",
        "--mcp-servers-json",
        "/absolute/path/to/mcp-servers.json"
      ]
    }
  }
}

mcp-servers.json usa o mesmo formato mcpServers que o próprio Claude Desktop usa, então você pode apontar --mcp-servers-json para sua configuração existente do Claude Desktop para reexpor os mesmos servidores filhos através da camada de seleção de ferramentas do MCP Deck:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

Trabalhando a partir de um checkout local em vez de git+https (por exemplo, durante o desenvolvimento)? Aponte uv run --project para ele em vez de uvx:

{
  "mcpServers": {
    "mcpdeck": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/mcpdeck",
        "mcpdeck",
        "serve",
        "--mcp-servers-json",
        "/absolute/path/to/mcp-servers.json"
      ]
    }
  }
}

serve suporta --setup (padrão --no-setup) se você quiser que ele também detecte/inicie um runtime de contêiner e o Qdrant antes de servir — veja mcpdeck serve --help. Reinicie o Claude Desktop / Claude Code após editar a configuração.

A interface web Gradio está desabilitada no caminho serve mesmo que sua configuração defina web_ui.enabled: true — o launch() do Gradio imprime no stdout, o que corromperia o canal JSON-RPC. Use mcpdeck start quando quiser o dashboard.

`find_tools` e namespace de ferramentas

Cada ferramenta filha é publicada sob {server_name}__{tool_name} (pontos não são permitidos em nomes de ferramentas MCP, então server.tool vira server__tool; qualquer outro caractere não permitido é substituído por -, e o nome é truncado para os 64 caracteres exigidos pelo MCP). Chame-as diretamente como qualquer outra ferramenta MCP.

find_tools é uma meta-ferramenta integrada, sempre listada primeiro, que executa a seleção inteligente do MCP Deck (vetor / LLM / RAG, dependendo da configuração e do que foi inicializado com sucesso) contra uma consulta em linguagem natural:

{"name": "find_tools", "arguments": {"query": "read a file from disk", "max_results": 5}}

Ela retorna uma lista JSON de {"name": ..., "description": ..., "server": ...} para as ferramentas mais relevantes, que você então chama diretamente pelo nome com namespace. Este é o principal objetivo do MCP Deck: em vez de um cliente ver todas as ferramentas de todos os servidores filhos de uma vez, ele pode pedir apenas as relevantes para a tarefa atual.

Início Rápido (modo dashboard)

Execute o dashboard/roteador (start) diretamente deste repositório com uvx:

# Automatic setup: detects Docker/Apple Container, starts Qdrant, opens the
# web UI on http://localhost:8080
uvx --from git+https://github.com/anirudhlath/mcpdeck mcpdeck

# With explicit config
uvx --from git+https://github.com/anirudhlath/mcpdeck mcpdeck \
    --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/mcpdeck
mcpdeck

Executar mcpdeck sem argumentos (ou com flags de nível superior como --config/--web-ui, sem subcomando) executa start. Na inicialização, ele irá:

Detectar e configurar um runtime de contêiner (Docker ou Apple Container Framework)
Iniciar o banco de dados vetorial Qdrant (a menos que --no-setup)
Detectar automaticamente uma configuração existente de mcp-servers.json ou Claude Desktop em locais padrão (somente leitura — ele não grava nem modifica sua configuração do Claude Desktop)
Iniciar o servidor MCP Deck com a interface web em http://localhost:8080

Arquitetura

flowchart TD
    subgraph Server["MCP Deck server"]
        Engine["Routing engine<br/>(primary strategy + fallback)"]
        Vector["Vector search router"]
        LLM["LLM router"]
        RAG["RAG router"]
        Pipeline["RAG pipeline<br/>(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<br/>(Claude Desktop / Claude Code)"] -->|"MCP over stdio<br/>(mcpdeck serve)"| Engine

    Vector --> Qdrant[("Qdrant<br/>tool + doc embeddings")]
    Pipeline --> Qdrant
    Emb -->|primary| LMS["LM Studio<br/>embeddings + local LLM"]
    Emb -.->|fallback| ST["sentence-transformers<br/>(local model)"]
    LLM --> LMS
    Pipeline --> LMS

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

Componentes principais (todos sob src/mcpdeck/):

Servidor MCP north-bound (server/mcp_stdio.py): o ponto de entrada mcpdeck serve — encapsula MetaMCPServer no protocolo MCP stdio, publica nomes {server}__{tool} e fornece find_tools
Núcleo do servidor (server/meta_server.py): inicializa e é dono de todos os outros componentes; inicialização resiliente significa que um componente de embedding/armazenamento vetorial/LLM/RAG com falha é registrado como aviso e deixado None em vez de causar falha — as ferramentas filhas ainda são expostas mesmo sem Qdrant/LM Studio em execução
Estratégias de roteamento (routing/): busca vetorial (vector_router.py), seleção por LLM (llm_router.py) e seleção baseada em RAG (rag_router.py)
Pipeline RAG (rag/pipeline.py): divide em blocos e indexa a documentação dos servidores filhos, recupera contexto relevante e aumenta as consultas de seleção
Serviço de embedding (embeddings/service.py): embeddings do LM Studio quando disponíveis, com fallback automático para sentence-transformers e cache local
Armazenamento vetorial (vector_store/qdrant_client.py): armazenamento baseado em Qdrant e busca por similaridade para embeddings de ferramentas e documentação
Gerenciador de servidores filhos (child_servers/): inicia e gerencia o ciclo de vida dos servidores MCP downstream e faz proxy das chamadas de ferramentas para eles
Interface web (web_ui/): dashboard de monitoramento em tempo real e configuração baseado em Gradio (somente start; não usado por serve)
Saúde / configuração automática (health/): detecção de infraestrutura, verificações de saúde e configuração automática de Docker/Apple Container + Qdrant

Recursos

Seleção Inteligente de Ferramentas

Busca Vetorial (padrão): similaridade semântica rápida usando embeddings
Seleção por LLM: seleção de ferramentas com IA usando um LLM local (LM Studio)
Seleção Baseada em RAG: seleção aumentada por contexto usando documentação recuperada dos servidores filhos

Configuração Automática (`start` / `--setup`)

Detecção de runtime de contêiner: Apple Container Framework em macOS Apple Silicon, ou Docker em outros lugares
Inicia o Qdrant automaticamente
Detecta automaticamente uma configuração existente de mcp-servers.json ou Claude Desktop

Dashboard Web (somente `start`)

Monitoramento de servidor em tempo real e logs
Editor de configuração interativo
Análises e métricas de uso de ferramentas
Monitoramento de status dos servidores filhos
Autenticação básica HTTP opcional (web_ui.auth_enabled + username/password; falha segura — a interface se recusa a iniciar se habilitada sem ambas as credenciais)

Configuração

Detecção Automática

mcpdeck start (e mcpdeck puro) procura arquivos de configuração nestes locais quando --config/--mcp-servers-json não são fornecidos:

Configuração Principal (mcpdeck.yaml):

./config/mcpdeck.yaml
./mcpdeck.yaml
~/.mcpdeck/config.yaml
./config/meta-server.yaml (legado, pré-renomeação)
./meta-server.yaml (legado, pré-renomeação)
~/.meta-mcp/config.yaml (legado, pré-renomeação)
/etc/meta-mcp/config.yaml (legado, pré-renomeação)

Configuração de Servidores MCP (JSON), somente leitura — nunca gravada:

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

mcpdeck serve não detecta automaticamente um mcp-servers.json do Claude Desktop (passe --mcp-servers-json explicitamente — veja a seção Claude Desktop/Code acima), mas quando --config é omitido, ele ainda procura nos mesmos locais de configuração principal que start, na ordem listada acima (usando padrões integrados se nenhum existir).

Criando Configuração Personalizada

mcp-servers.json (formato Claude Desktop):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

mcpdeck.yaml (todo campo é real e validado — campos desconhecidos são rejeitados; veja examples/simple-config.yaml e examples/advanced-config.yaml para exemplos completos e funcionais):

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

web_ui:
  enabled: true
  port: 8080
  auth_enabled: false    # set true + username/password for basic auth

embeddings:
  # Primary: LM Studio (optional). Canonical endpoint form ends in /v1 —
  # /v1/ and /v1/embeddings are also accepted and normalized.
  lm_studio_endpoint: "http://localhost:1234/v1"
  lm_studio_model: "nomic-embed-text-v1.5"

  # Fallback: local sentence-transformers model (automatic)
  fallback_model: "all-MiniLM-L6-v2"

vector_store:
  type: "qdrant"
  host: "localhost"
  port: 6333

Valide qualquer arquivo de configuração antes de confiar nele:

uv run mcpdeck validate-config path/to/mcpdeck.yaml

Comandos

mcpdeck [OPTIONS] COMMAND [ARGS]...

Executar mcpdeck sem subcomando, ou com uma flag de nível superior (por exemplo, mcpdeck --config x.yaml --web-ui), roteia para start.

Comando	Finalidade
`serve`	Executa o servidor MCP via stdio para Claude Desktop/Code (veja acima)
`start`	Modo dashboard/full-stack com configuração automática + interface web (comando padrão)
`run`	Inicia o servidor sem configuração automática ou detecção automática de configuração
`validate-config FILE`	Valida um arquivo de configuração
`list-strategies`	Lista as estratégias de seleção de ferramentas disponíveis
`debug-vector`	Executa uma consulta de teste contra o índice de busca vetorial
`regenerate-embeddings`	Recalcula embeddings de ferramentas (`--force` para limpar e reconstruir)
`init-config`	Grava um `mcpdeck.yaml` padrão
`health`	Verifica a saúde do sistema e dependências

Todo comando suporta --help para suas flags exatas, por exemplo, mcpdeck serve --help. Ao executar via uvx, prefixe-as com uvx --from git+https://github.com/anirudhlath/mcpdeck.

`health`

uv run mcpdeck health                    # text output, exits non-zero on issues
uv run mcpdeck health --output-format json
uv run mcpdeck health --fix --setup-docker --download-models

Docker

docker-compose.yml executa o Qdrant além do serviço de dashboard mcpdeck (construído a partir do Dockerfile do repositório, usando config/docker.yaml que vincula a interface web a 0.0.0.0:8080 e aponta vector_store.host para o serviço qdrant):

docker-compose up -d
# Web UI: http://localhost:8080
# Qdrant: http://localhost:6333/collections

O CMD do contêiner é mcpdeck start --no-setup --config /app/config/docker.yaml (o Qdrant é fornecido pelo compose, então a configuração é ignorada); seu HEALTHCHECK faz curl em http://localhost:8080/ (a raiz do dashboard Gradio — não há endpoint HTTP /health).

Para executar o Qdrant via framework de contêiner da Apple em vez de Docker, veja docs/apple-container-setup.md.

Desenvolvimento

git clone https://github.com/anirudhlath/mcpdeck.git
cd mcpdeck

uv sync --extra dev
uv run pre-commit install

uv run pytest
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/
# or all at once:
./scripts/check-all.sh

# Run the stdio server against a local checkout:
uv run mcpdeck serve --no-setup --mcp-servers-json path/to/mcp-servers.json --log-level DEBUG

# Run dashboard mode against a local checkout:
uv run mcpdeck start --log-level DEBUG

Os testes são marcados como unit, integration (podem iniciar subprocessos reais; não requerem Docker/Qdrant — a inicialização resiliente é exercitada diretamente) e slow.

Solução de Problemas

Falha na conexão com Qdrant

curl http://localhost:6333/collections
uv run mcpdeck health --setup-docker

Atualizando de antes da v0.2.0: os IDs de pontos do armazenamento vetorial e as chaves de cache de embedding mudaram (o esquema antigo usava um hash com salt por processo que produzia pontos duplicados a cada reinicialização). Execute isto uma vez após a atualização:

uv run mcpdeck regenerate-embeddings --force

Nenhum servidor MCP encontrado: crie um arquivo mcp-servers.json, ou aponte --mcp-servers-json para uma configuração existente do Claude Desktop.

Interface web inacessível: verifique se a porta não está em uso (lsof -i :8080) ou escolha outra com --port.

LM Studio não está sendo usado: confirme se o endpoint responde em http://localhost:1234/v1/models e se lm_studio_endpoint está definido (está null/não definido por padrão — o modelo de fallback sentence-transformers é usado a menos que você o configure explicitamente).

Logs: stderr no modo serve; ./logs/mcpdeck.log e o visualizador de logs da interface web no modo start/run (caminho de logging.file na sua configuração).

Considerações de Segurança

Execute servidores filhos com privilégios mínimos
Use variáveis de ambiente para configuração sensível (expansão ${VAR} em blocos env de servidores filhos)
Revise as configurações dos servidores filhos antes do uso
Habilite web_ui.auth_enabled (+ username/password) se o dashboard estiver acessível além do localhost

Contribuindo

Faça um fork do repositório e clone seu fork
uv sync --extra dev && uv run pre-commit install
Crie um branch de feature, faça suas alterações com testes (o pre-commit executa Ruff format/lint e mypy no commit)
./scripts/check-all.sh antes de abrir um PR

Licença

MIT License - consulte o arquivo LICENSE para obter detalhes.