Meta MCP Server

Un servidor MCP para el enrutamiento inteligente de herramientas, que utiliza una base de datos vectorial Qdrant y LM Studio para embeddings.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Deck

Tu panel de control para servidores MCP. MCP Deck es un enrutador MCP (Model Context Protocol) inteligente: inicia tus servidores MCP hijos, integra sus herramientas y las expone a un cliente MCP a través de una única conexión — ya sea proxy de cada herramienta directamente (con espacios de nombres) o, a través de la meta-herramienta find_tools, permitiendo que el cliente pregunte "¿qué herramienta debería usar para X?" y reciba las más relevantes en lugar de la lista completa.

Hay dos formas de ejecutarlo:

mcpdeck serve — un servidor MCP sobre stdio para Claude Desktop / Claude Code (o cualquier cliente MCP). Esta es la integración que la mayoría de la gente quiere.
mcpdeck start — un proceso independiente de panel/enrutador con una interfaz web Gradio, útil para desarrollo, depuración de selección de herramientas e inspección de la salud de los servidores hijos fuera de un cliente MCP.

Instala vía uvx/uv tool install desde git como se muestra abajo, o una vez que se publique una versión etiquetada en PyPI, uv tool install mcpdeck / uvx mcpdeck.

Requisitos previos

Python 3.11+
uv — proporciona los comandos uvx y uv utilizados en todo este README. Si solo tienes pipx, ejecuta pipx install uv para obtener uvx.
Docker o Apple Container (macOS Apple Silicon) — necesario para ejecutar Qdrant, que respalda la selección de herramientas basada en vectores. Opcional si solo usas --no-setup contra un Qdrant ya en ejecución, o si no necesitas enrutamiento de selección de herramientas.
LM Studio (opcional) — para embeddings locales y selección de herramientas basada en LLM. Sin él, MCP Deck recurre automáticamente a un modelo sentence-transformers incluido.

Uso con Claude Desktop / Claude Code

Este es el camino mcpdeck serve: un servidor MCP sobre stdio que expone cada herramienta hija como {server}__{tool} más una meta-herramienta find_tools. stdout está reservado para el protocolo JSON-RPC — todos los registros y salida legible van a stderr, por lo que es seguro ejecutarlo bajo el supervisor de procesos de cualquier cliente MCP.

Añade a la configuración de tu cliente MCP (el claude_desktop_config.json de Claude Desktop, o el .mcp.json de 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 la misma forma mcpServers que usa el propio Claude Desktop, por lo que puedes apuntar --mcp-servers-json a tu configuración existente de Claude Desktop para re-exponer los mismos servidores hijos a través de la capa de selección de herramientas de MCP Deck:

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

¿Trabajando desde un checkout local en lugar de git+https (por ejemplo, durante el desarrollo)? Apunta uv run --project a él en lugar de uvx:

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

serve admite --setup (por defecto --no-setup) si quieres que también detecte/inicie un runtime de contenedores y Qdrant antes de servir — consulta mcpdeck serve --help. Reinicia Claude Desktop / Claude Code después de editar la configuración.

La interfaz web Gradio está deshabilitada en el camino serve incluso si tu configuración establece web_ui.enabled: true — el launch() de Gradio imprime a stdout, lo que corrompería el canal JSON-RPC. Usa mcpdeck start cuando quieras el panel.

`find_tools` y espacios de nombres de herramientas

Cada herramienta hija se publica bajo {server_name}__{tool_name} (los puntos no son legales en los nombres de herramientas MCP, por lo que server.tool se convierte en server__tool; cualquier otro carácter no permitido se reemplaza con -, y el nombre se trunca a los 64 caracteres exigidos por MCP). Llámalas directamente como cualquier otra herramienta MCP.

find_tools es una meta-herramienta integrada, siempre listada primero, que ejecuta la selección inteligente de MCP Deck (vector / LLM / RAG, según la configuración y lo que se inicializó correctamente) contra una consulta en lenguaje natural:

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

Devuelve una lista JSON de {"name": ..., "description": ..., "server": ...} para las herramientas más relevantes, que luego llamas directamente por su nombre con espacio de nombres. Este es el punto principal de MCP Deck: en lugar de que un cliente vea todas las herramientas de cada servidor hijo a la vez, puede pedir solo las relevantes para la tarea actual.

Inicio rápido (modo panel)

Ejecuta el panel/enrutador (start) directamente desde este repositorio con 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

Ejecutar mcpdeck sin argumentos (o con banderas de nivel superior como --config/--web-ui, sin subcomando) ejecuta start. Al inicio:

Detecta y configura un runtime de contenedores (Docker o Apple Container Framework)
Inicia la base de datos vectorial Qdrant (a menos que --no-setup)
Auto-detecta una configuración existente de mcp-servers.json o Claude Desktop en ubicaciones estándar (solo lectura — no escribe ni modifica tu configuración de Claude Desktop)
Inicia el servidor MCP Deck con la interfaz web en http://localhost:8080

Arquitectura

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 principales (todos bajo src/mcpdeck/):

Servidor MCP north-bound (server/mcp_stdio.py): el punto de entrada mcpdeck serve — envuelve MetaMCPServer en el protocolo MCP stdio, publica nombres {server}__{tool} y proporciona find_tools
Núcleo del servidor (server/meta_server.py): inicializa y posee todos los demás componentes; el inicio resiliente significa que un componente fallido de embedding/almacén vectorial/LLM/RAG se registra como advertencia y se deja None en lugar de fallar — las herramientas hijas aún se exponen incluso sin Qdrant/LM Studio en ejecución
Estrategias de enrutamiento (routing/): búsqueda vectorial (vector_router.py), selección LLM (llm_router.py) y selección basada en RAG (rag_router.py)
Pipeline RAG (rag/pipeline.py): fragmenta e indexa la documentación de los servidores hijos, recupera contexto relevante y aumenta las consultas de selección
Servicio de embeddings (embeddings/service.py): embeddings de LM Studio cuando están disponibles, con respaldo automático de sentence-transformers y caché local
Almacén vectorial (vector_store/qdrant_client.py): almacenamiento basado en Qdrant y búsqueda de similitud para embeddings de herramientas y documentación
Gestor de servidores hijos (child_servers/): inicia y gestiona el ciclo de vida de los servidores MCP downstream y proxya las llamadas de herramientas hacia ellos
Interfaz web (web_ui/): panel de monitoreo y configuración en tiempo real basado en Gradio (solo start; no usado por serve)
Salud / auto-configuración (health/): detección de infraestructura, verificaciones de salud y configuración automática de Docker/Apple Container + Qdrant

Características

Selección inteligente de herramientas

Búsqueda vectorial (por defecto): similitud semántica rápida usando embeddings
Selección LLM: selección de herramientas impulsada por IA usando un LLM local (LM Studio)
Selección basada en RAG: selección aumentada por contexto usando documentación recuperada de servidores hijos

Configuración automática (`start` / `--setup`)

Detección de runtime de contenedores: Apple Container Framework en Apple Silicon macOS, o Docker en otros casos
Inicia Qdrant automáticamente
Auto-detecta una configuración existente de mcp-servers.json o Claude Desktop

Panel web (solo `start`)

Monitoreo de servidor en tiempo real y registros
Editor de configuración interactivo
Analíticas y métricas de uso de herramientas
Monitoreo de estado de servidores hijos
Autenticación básica HTTP opcional (web_ui.auth_enabled + username/password; falla cerrado — la interfaz se niega a iniciar si está habilitada sin ambas credenciales)

Configuración

Auto-detección

mcpdeck start (y mcpdeck sin argumentos) busca archivos de configuración en estas ubicaciones cuando --config/--mcp-servers-json no se proporcionan:

Configuración principal (mcpdeck.yaml):

./config/mcpdeck.yaml
./mcpdeck.yaml
~/.mcpdeck/config.yaml
./config/meta-server.yaml (legado, pre-renombrado)
./meta-server.yaml (legado, pre-renombrado)
~/.meta-mcp/config.yaml (legado, pre-renombrado)
/etc/meta-mcp/config.yaml (legado, pre-renombrado)

Configuración de servidores MCP (JSON), solo lectura — nunca se escribe:

./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 no auto-detecta un mcp-servers.json de Claude Desktop (pasa --mcp-servers-json explícitamente — consulta la sección de Claude Desktop/Code arriba), pero cuando --config se omite, aún busca en las mismas ubicaciones de configuración principal que start, en el orden listado arriba (recurriendo a valores predeterminados integrados si no existen).

Crear configuración 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 (cada campo es real y validado — los campos desconocidos son rechazados; consulta examples/simple-config.yaml y examples/advanced-config.yaml para ejemplos completos y funcionales):

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

Valida cualquier archivo de configuración antes de confiar en él:

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

Comandos

mcpdeck [OPTIONS] COMMAND [ARGS]...

Ejecutar mcpdeck sin subcomando, o con una bandera de nivel superior (por ejemplo, mcpdeck --config x.yaml --web-ui), enruta a start.

Comando	Propósito
`serve`	Ejecuta el servidor MCP sobre stdio para Claude Desktop/Code (ver arriba)
`start`	Modo panel/stack completo con auto-configuración + interfaz web (comando por defecto)
`run`	Inicia el servidor sin auto-configuración ni auto-detección de configuración
`validate-config FILE`	Valida un archivo de configuración
`list-strategies`	Lista las estrategias de selección de herramientas disponibles
`debug-vector`	Ejecuta una consulta de prueba contra el índice de búsqueda vectorial
`regenerate-embeddings`	Recalcula los embeddings de herramientas (`--force` para limpiar y reconstruir)
`init-config`	Escribe un `mcpdeck.yaml` por defecto
`health`	Verifica la salud del sistema y las dependencias

Cada comando admite --help para sus banderas exactas, por ejemplo, mcpdeck serve --help. Cuando se ejecuta vía uvx, prefija estos con 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 ejecuta Qdrant más el servicio de panel mcpdeck (construido desde el Dockerfile del repositorio, usando config/docker.yaml que vincula la interfaz web a 0.0.0.0:8080 y apunta vector_store.host al servicio qdrant):

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

El CMD del contenedor es mcpdeck start --no-setup --config /app/config/docker.yaml (Qdrant lo proporciona compose, por lo que la configuración se omite); su HEALTHCHECK hace curl a http://localhost:8080/ (la raíz del panel Gradio — no hay un endpoint HTTP /health).

Para ejecutar Qdrant mediante el framework de contenedores de Apple en lugar de Docker, consulta docs/apple-container-setup.md.

Desarrollo

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

Las pruebas están marcadas como unit, integration (pueden iniciar subprocesos reales; no se requiere Docker/Qdrant — la inicialización resiliente se ejercita directamente) y slow.

Solución de problemas

Falló la conexión a Qdrant

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

Actualización desde antes de v0.2.0: los IDs de puntos del almacén vectorial y las claves de caché de embeddings cambiaron (el esquema anterior usaba un hash salado por proceso que producía puntos duplicados en cada reinicio). Ejecuta esto una vez después de actualizar:

uv run mcpdeck regenerate-embeddings --force

No se encontraron servidores MCP: crea un archivo mcp-servers.json, o apunta --mcp-servers-json a una configuración existente de Claude Desktop.

La interfaz web no es accesible: verifica que el puerto no esté ya en uso (lsof -i :8080) o elige otro con --port.

LM Studio no se está usando: confirma que el endpoint responde en http://localhost:1234/v1/models, y que lm_studio_endpoint está configurado (está null/sin configurar por defecto — se usa el modelo de respaldo sentence-transformers a menos que lo configures explícitamente).

Registros: stderr en modo serve; ./logs/mcpdeck.log y el visor de registros de la interfaz web en modo start/run (ruta desde logging.file en tu configuración).

Consideraciones de seguridad

Ejecuta servidores hijos con privilegios mínimos
Usa variables de entorno para configuración sensible (expansión ${VAR} en bloques env de servidores hijos)
Revisa las configuraciones de los servidores hijos antes de usarlos
Habilita web_ui.auth_enabled (+ username/password) si el panel es accesible más allá de localhost

Contribuciones

Haz un fork del repositorio y clona tu fork
uv sync --extra dev && uv run pre-commit install
Crea una rama de características, haz tus cambios con pruebas (pre-commit ejecuta Ruff format/lint y mypy al confirmar)
./scripts/check-all.sh antes de abrir un PR

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles.