GitHub Tools MCP Server

Un servidor real de Model Context Protocol que expone herramientas de solo lectura contra la API REST de GitHub — instalable en Claude Desktop o Claude Code en menos de un minuto — además de una demo web independiente que ejercita la misma lógica de herramientas a través de una interfaz de chat normal.

Demo en vivo: https://mcp-demo-phi.vercel.app/demo

Estado: qué es, qué no es

Funcionando y desplegado. Las 5 herramientas verificadas contra datos reales de GitHub, 42 comprobaciones automáticas distribuidas en 3 suites de pruebas, y la aplicación completa confirmada como activa en la URL de producción real. Consulta DESIGN_LOG.md para el relato en curso y honesto de cada decisión y error por el camino.

La demo web NO es un transporte MCP. Es un FastAPI sencillo que llama directamente a las mismas funciones de tools.py como Python, sin hablar el protocolo MCP. Es una distinción genuinamente útil a la que conviene ser precisos — véase la sección 3 de DESIGN_LOG.md para entender por qué aquí no se intenta un transporte MCP remoto real.

Related MCP server: GitHub MCP Connector

Arquitectura

                    ┌─────────────────────┐
                    │      tools.py        │  <- 5 pure functions, no
                    │  (GitHub REST calls   │     MCP-specific code
                    │   via github_client)   │
                    └──────────┬───────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                  │
    ┌─────────▼─────────┐            ┌───────────▼──────────┐
    │     server.py       │            │     api/index.py       │
    │  MCPServer, stdio    │            │  FastAPI, POST /chat    │
    │  transport            │            │  real Claude tool-      │
    │  -> Claude Desktop/    │            │  calling loop over       │
    │     Claude Code        │            │  the same tools           │
    └─────────────────────┘            └────────────────────────┘
     THE MCP SERVER                      A PLAIN HTTP DEMO OF
     (the real deliverable)              THE SAME TOOL LOGIC

Instalación

cp .env.example .env   # GITHUB_TOKEN (both halves), ANTHROPIC_API_KEY (web demo only)
pip install -r requirements.txt

Ejecutar el servidor MCP en local

python3 server.py

Para añadir a Claude Desktop: edita %APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), fusiona el contenido de claude_desktop_config.example.json (complete con tu GITHUB_TOKEN real y la ruta absoluta hacia server.py), y entonces reinicia Claude Desktop. Para añadir a Claude Code: claude mcp add o edita el .mcp.json de tu proyecto de la misma manera.

Flujo de trabajo de desarrollo manual interactivo: el SDK incorpora un inspector para manejar el servidor a mano sin un cliente completo — npx @modelcontextprotocol/inspector python3 server.py.

Ejecutar la demo web en local

export $(cat .env | xargs)
uvicorn api.index:app --reload --port 8020

Registro de diseño

Cada decisión no evidente, junto con la superficie de la API del SDK verificada contra el paquete realmente instalado en lugar de asumida a partir de una documentación posiblemente desactualizada, está en DESIGN_LOG.md.