GitHub Analytics MCP Server

Un servidor Model Context Protocol (MCP) 2.x de nivel de producción para análisis de GitHub.

Este proyecto va más allá de un tutorial básico de MCP y demuestra cómo construir un servidor MCP con los patrones de ingeniería que realmente necesitas para un uso en el mundo real:

• HTTP asíncrono

• Agrupación de conexiones

• Tiempos de espera explícitos

• Caché TTL

• Conocimiento de los límites de velocidad de GitHub

• Reintentos con retroceso exponencial

• Registro estructurado

• Validación de entradas

• Solicitudes paralelas a la API

• Gestión limpia del ciclo de vida de MCP

• Pruebas reales de extremo a extremo del protocolo MCP

Construido como parte de la serie Production AI Engineering en Agentic Data Lab.

🎥 YouTube: Agentic Data Lab

¿Qué hace este servidor MCP?

El servidor expone análisis de repositorios de GitHub como herramientas MCP.

Un cliente de IA compatible con MCP puede usarlo para:

• inspeccionar metadatos del repositorio

• recuperar commits recientes

• analizar contribuidores

• inspeccionar issues abiertos

• analizar la actividad de commits

• comparar dos repositorios

• inspeccionar los límites de velocidad de la API de GitHub

Ejemplo:

User:
Compare pallets/flask and django/django.

Which repository looks more active?

El cliente de IA puede llamar a:

compare_repos

y recuperar datos en vivo de GitHub a través de este servidor MCP.

Arquitectura

                ┌─────────────────────┐
                │   MCP Client / AI   │
                │ Claude / MCP Client │
                └──────────┬──────────┘
                           │
                           │ MCP stdio
                           ▼
                ┌─────────────────────┐
                │ GitHub Analytics    │
                │     MCP Server      │
                └──────────┬──────────┘
                           │
                 ┌─────────┴─────────┐
                 │                   │
                 ▼                   ▼
          Input Validation       TTL Cache
                                     │
                           ┌─────────┴─────────┐
                           │                   │
                      CACHE HIT          CACHE MISS
                           │                   │
                           │                   ▼
                           │          Async HTTP Client
                           │                   │
                           │          Retry + Backoff
                           │                   │
                           │                   ▼
                           │            GitHub REST API
                           │                   │
                           └───────────◄───────┘
                                       │
                                       ▼
                               Structured MCP Result

7 patrones de producción implementados

1. HTTP asíncrono + agrupación de conexiones

El servidor utiliza:

httpx.AsyncClient

en lugar de solicitudes HTTP síncronas.

El cliente HTTP se crea una vez durante el ciclo de vida del servidor MCP y se reutiliza en todas las llamadas a herramientas.

Esto proporciona:

• E/S no bloqueante

• reutilización de conexiones

• mejor concurrencia

• control explícito de tiempos de espera

El servidor configura tiempos de espera separados para:

connect
read
write
pool

Related MCP server: ship-it-mcp

2. Caché TTL

Los clientes de IA pueden llamar a la misma herramienta MCP varias veces durante una conversación.

En lugar de consultar a GitHub cada vez, el servidor almacena las respuestas en memoria.

Ejemplo:

First request

MCP Client
    │
    ▼
MCP Server
    │
    ▼
GitHub API
    │
    ▼
Cache

Segunda solicitud:

MCP Client
    │
    ▼
MCP Server
    │
    ▼
CACHE HIT

No se requiere ninguna solicitud adicional a GitHub.

Las distintas herramientas utilizan diferentes TTL según la rapidez con la que cambian sus datos.

3. Conocimiento de los límites de velocidad de GitHub

GitHub expone información sobre los límites de velocidad a través de las cabeceras de respuesta.

El servidor rastrea:

X-RateLimit-Limit
X-RateLimit-Used
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After

El servidor puede detectar cuándo GitHub está limitando realmente la velocidad de las solicitudes y devolver un error de herramienta MCP útil en lugar de exponer una excepción sin procesar.

4. Reintentos + retroceso exponencial

Los fallos de red transitorios y las respuestas 5xx ascendentes se reintentan automáticamente.

Secuencia de reintentos:

Attempt 1
   │
   └── failure
        │
        ▼
      wait 1s

Attempt 2
   │
   └── failure
        │
        ▼
      wait 2s

Attempt 3
   │
   └── final result

La fórmula de retroceso es:

2 ** (attempt - 1)

El servidor no reintenta ciegamente los errores normales de cliente 4xx.

5. Registro estructurado

MCP stdio usa stdout para la comunicación del protocolo.

Por lo tanto, los registros operativos se escriben por separado a través del logging de Python.

Ejemplo:

2026-08-27T14:14:03 | INFO | Starting GitHub Analytics MCP server
2026-08-27T14:14:04 | INFO | GET /repos/facebook/react → 200
2026-08-27T14:14:04 | INFO | CACHE HIT /repos/facebook/react

Esto facilita la inspección de:

• solicitudes a la API

• estado HTTP

• latencia

• intentos de reintento

• aciertos de caché

• errores de validación

• advertencias de límite de velocidad

6. Validación de entrada

El propietario del repositorio y los nombres del repositorio se validan antes de realizar cualquier solicitud de red.

Los nombres válidos pueden contener:

letters
numbers
.
-
_

Por ejemplo:

face../../book

se rechaza localmente antes de que pueda formar parte de una solicitud a la API de GiHub.

7. Solicitudes paralelas a la API

La herramienta MCP compare_repos necesita información de dos repositorios independientes.

En lugar de obtnerlos secuencialmente:

repo_a = await get_repo_a()
repo_b = await get_repo_b()

el servidor ejecuta ambas solicitudes de forma concurrene:

repo_a, repo_b = await asyncio.gather(
    get_repo_a(),
    get_repo_b(),
)

Conceptualmen:

Sequential

Repo A ───────────────► Done
                        Repo B ───────────────► Done


Parallel

Repo A ───────────────► Done
Repo B ───────────────────► Done

Esto reduce el tiempo de espera transcurrido cuando las solicitudes son independienes.

Herramientas MCP disponbles

El servidor expone actualmen 7 herramienas MCP.

get_repo_overview

Devuelve:

• estrelas

• bifurcaciones (forks)

• issues abiertos

• wachers

• lenguae

• temas

• licencia

• feha del últio push

• página de inicio

• tamaño del repositorio

Ejemplo:

get_repo_overview(
    owner="facebook",
    repo="react"
)

list_recent_commits

Devuelve los commis recientes del repositorio.

Ejemplo:

list_recent_commits(
    owner="vuejs",
    repo="core",
    limit=5
)

get_contributors

Devuelve los principaes contribuidores del repositorio.

Ejemplo:

get_contributors(
    owner="django",
    repo="django",
    limit=10
)

list_open_issues

Devuelve los issues abiertos de GiHub excluyendo las pul requests.

Ejemplo:

list_open_issues(
    owner="pallets",
    repo="flask",
    limit=10
)

get_commit_activity

Devuelve la actividad de commis del repositorio, incluyendo:

• total de commis

• media de commis por seman

• actividad máxma

• actividad semana reciente

compare_repos

Compara dos repositorios lado a lado.

Ejemplo:

compare_repos(
    owner1="pallets",
    repo1="flask",
    owner2="django",
    repo2="django"
)

Los campos devueltos incluyen:

stars
forks
open issues
language
last push

get_rate_limit_status

Devuelve información sobre los límies de velocidad de la API de GiHub además de contadores locaes del servidor MCP.

Ejemplo:

{
  "limit": 60,
  "used": 4,
  "remaining": 56,
  "resets_in_seconds": 3599,
  "server_outbound_http_requests": 4,
  "server_cache_hits": 1
}

Los vaores reaes dependen de tu uso actua de la API de GiHub.

Estructura del proyeco

mcp-github-analytics/
│
├── server.py
│   └── Main MCP server and GitHub tools
│
├── demo_mcp.py
│   └── Real end-to-end MCP client demo
│
├── requirements.txt
│   └── Python dependencies
│
├── .env.example
│   └── Environment variable template
│
└── .gitignore

Configuración

1. Clonar el repositorio

git clone https://github.com/sweta2503/mcp-github-analytics.git

Entra en el proyecto:

cd mcp-github-analytics

2. Crear un entorno virtual

python -m venv .venv

macOs / Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

3. Instalar las dependencias

pip install -r requirements.txt

El proyecto utiliza:

mcp[cli]==2.1.1
httpx==0.28.1
python-dotenv==1.2.3

Configuración del token de GitHub

Un token de GitHub es opciona cuando se trabaja solo con repositorios públicos, pero es recomendable.

Copia el archivo de entorno de ejemlo:

cp .env.example .env

Añade tu token de GiHub:

GITHUB_TOKEN=your_github_token_here

No hagas commit de tu archivo .env real ni de tu token.

Ejecutar la demo real de MCP

Ejecuta:

python demo_mcp.py

Esta es una prueba real de MCP de extremo a extremo.

demo_mcp.py no importa simplemente las funciones de server.py.

En su lugar:

1. Starts server.py as an MCP subprocess
2. Connects using MCP stdio
3. Negotiates the MCP protocol
4. Discovers the MCP tools
5. Calls the tools through MCP
6. Receives structured MCP responses

Deberías ver una salida similar a:

MCP CONNECTED — discover the real server tools

Negotiated protocol: ...
Tools discovered (7):
get_repo_overview
list_recent_commits
get_contributors
list_open_issues
get_commit_activity
compare_repos
get_rate_limit_status

Probar la caché

La demo llama a:

get_repo_overview(facebook/react)

dos veces.

La primera llamada consulta a GiHub.

La segunda debería mostar:

CACHE HIT

y devolver el resutado mucho más rápido.

Probar la comparación paraela de repositorios

La demo también ejecuta:

compare_repos(
    pallets/flask,
    django/django
)

Ambas solicitudes a GiHub (upstream) se lanzan de forma concurrene a través de:

asyncio.gather(...)

Capturar la salida de la demo y los registros del servidor

Puedes capturar la salida del cliene MCP y los registros del servidor por separado:

python demo_mcp.py > demo_output.txt 2> server.log

Esto crea:

demo_output.txt

para las respuestas del cliene MCP y:

server.log

para los registros del lado del servidor.

El registro del servidor contiene información úti como:

GET /repos/facebook/react → 200
CACHE HIT /repos/facebook/react
GET /repos/pallets/flask → 200
GET /repos/django/django → 200

Ejecutar el servidor directamente

Puedes iniciar el propio servidor MCP con:

python server.py

El servidor se ejecuta a través de MCP stdio.

Normalmen, un cliene compatibe con MCP inicia este proceso automáticamen.

Conectar el servidor a Claude Desktop

No es necesaio mantener un claude_desktop_config.json específico de la máquina dentro de este repositorio.

En su lugar, añade el servidor a tu configuración local de Claude Desktop.

Ejemplo:

{
  "mcpServers": {
    "github-analytics": {
      "command": "/ABSOLUTE/PATH/TO/mcp-github-analytics/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-github-analytics/server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Reemplaza:

/ABSOLUTE/PATH/TO/mcp-github-analytics

con la ubicación real del proyecto en tu ordenador.

Nunca hagas commit de tu token real de GitHub.

Después de reiniciar Claude Desktop, las herramientas de análisis de GitHub deberían estar disponibles para Claude.

Ejemplo de prompt:

Compare pallets/flask and django/django.

Which repository appears more active?

Use the GitHub MCP tools and explain which data you used.

Flujo de solicitud de extremo a extremo

User
 │
 ▼
Claude / MCP Client
 │
 │ MCP tool call
 ▼
GitHub Analytics MCP Server
 │
 ├── Validate input
 │
 ├── Check TTL cache
 │
 ├── Cache hit ──────────────► Return result
 │
 └── Cache miss
          │
          ▼
     Async HTTP
          │
     Retry / Backoff
          │
          ▼
     GitHub REST API
          │
          ▼
       Response
          │
          ▼
       TTL Cache
          │
          ▼
 Structured MCP Response
          │
          ▼
     AI / MCP Client

MCP local frente a MCP de producción distribuido

Este proyecto utiliza intencionadamente una caché TTL en memoria porque está diseñado como un ejemplo claro de MCP local/stdio.

Para un despliegue remoto de MCP con múltiples instancias, normalmente se reemplazaría el estado local del proceso por infraestructura como:

Redis
PostgreSQL
distributed rate limiting
centralized observability
authentication
tracing

Los patrones demostrados en este repositorio son los bloques de construcción para esa siguiente etapa.

Ver el desarrollo completo

Explico la arquitectura, el código, el caché, la lógica de reintentos, la validación, las solicitudes paralelas y la demo real de MCP en mi canal de YouTube:

🎥 Agentic Data Lab

https://www.youtube.com/@agenticdatalab

En el canal cubro:

• Production AI Engineering

• MCP

• Agentes de IA

• LangGraph

• RAG

• Evaluaciones de IA

• Observabilidad de agentes

• Diseño de sistemas de IA

• Ingeniería de datos + IA

• Benchmarks y experimentos de producción

Si te interesa crear sistemas de IA que vayan más allá de las demos de tutoriales, considera suscribirte.

👉 YouTube: Agentic Data Lab

Contribuciones

Se aceptan issues, mejoras y pull requests.

Si amplías el servidor MCP con otra herramienta útil de análisis de GitHub, no dudes en abrir un PR.

Apoya el proyecto

Si este repositorio te ha ayudado:

• ⭐ Marca el repositorio con una estrella

• 🍴 Hazle fork y crea tus propias herramientas MCP

• ▶️ Suscríbete a Agentic Data Lab

Pronto llegarán más proyectos de ingeniería de IA de producción.