GitHub MCP Server

MCP Server en Node.js + TypeScript que permite a un agente de IA (Claude) ejecutar operaciones reales en GitHub usando lenguaje natural: crear repositorios, abrir issues, hacer commits y más.

Proyecto Integrador M5 – Henry Full Stack · AutomateHub

¿Qué hace?

Expone 8 tools a través del Model Context Protocol (MCP). Un host compatible (VS Code con Claude) se conecta al server por stdio, el LLM lee las descripciones de los tools y decide cuál usar según lo que pide el usuario.

Usuario: "Creá un repo llamado demo-mcp y abrile un issue que diga 'Agregar tests'" → Claude llama a create_repository y luego a create_issue. Las acciones quedan hechas en GitHub.

Related MCP server: mcp-github-issues

¿Por qué es útil?

• Automatizar tareas repetitivas: crear repos con README inicial, abrir issues en serie, actualizar archivos sin salir del editor.

• Lenguaje natural en lugar de comandos: no hace falta recordar la sintaxis de git o de la API.

• Triage rápido: "¿Qué issues abiertos tiene mi repo X?" y cerrarlos o comentarlos desde el chat.

• Documentación al vuelo: "Agregá un archivo CONTRIBUTING.md con estas reglas" → commit directo.

Arquitectura

flowchart LR
    U[Usuario] -->|prompt en lenguaje natural| H[VS Code<br/>Host]
    H <--> L[Claude<br/>LLM / Client]
    L -->|tools/call vía JSON-RPC por stdio| S[GitHub MCP Server<br/>este proyecto]
    S -->|Octokit + token| G[(GitHub API)]
    G -->|respuesta JSON| S
    S -->|texto en lenguaje natural| L

VS Code (Host)            gestiona la sesión y lanza el server como proceso hijo
   │
Claude (LLM / Client)     lee el prompt, elige el tool y arma los parámetros
   │  JSON-RPC por stdio
MCP Server (este repo)    valida con Zod → llama a GitHub → traduce errores
   │  HTTPS (Octokit)
GitHub API                ejecuta la acción y devuelve el resultado

Flujo interno de una llamada:

server.ts → tools/*.ts → schemas (Zod) → github/operations.ts → utils/retry.ts → github/client.ts (Octokit)
                                                  ↓ si falla
                                          errors/index.ts (mensaje en lenguaje natural)

Estructura del proyecto

src/
├── server.ts              # Entry point: crea el McpServer, registra tools, conecta por stdio
├── types.ts               # Tipos compartidos (RepositorySummary, IssueSummary, ...)
├── tools/                 # Un archivo por tool: nombre + descripción + schema + handler
├── schemas/index.ts       # Schemas de Zod y helper validateInput()
├── github/
│   ├── client.ts          # Crea Octokit con el token (separado para poder mockearlo)
│   └── operations.ts      # Lógica de negocio: llamadas a la API de GitHub
├── errors/index.ts        # ValidationError, AuthenticationError, GitHubAPIError, NetworkError
└── utils/
    ├── logging.ts         # Logger a stderr que oculta tokens
    ├── retry.ts           # Exponential backoff para rate limit / red
    └── response.ts        # Arma las respuestas para el LLM
tests/
├── tools.test.ts          # Validación de schemas
├── github.test.ts         # Operaciones con Octokit mockeado
└── errors.test.ts         # Transformación de errores, retry y logs

Requisitos

• Node.js 18 o superior (node -v)

• npm (viene con Node)

• Visual Studio Code actualizado

• Una de estas dos opciones para usar Claude dentro de VS Code:

  • Extensión Claude Code (requiere cuenta de Claude con plan pago), o

  • GitHub Copilot en modo Agent con un modelo Claude seleccionado

• Una cuenta de GitHub y un Personal Access Token

Instalación

git clone https://github.com/<dantecaceres92>/github-mcp-server.git
cd github-mcp-server
npm install
npm run build        # compila TypeScript a la carpeta dist/

Configuración

1. Obtener un GitHub Personal Access Token

1. Entrá a GitHub → foto de perfil → Settings.

2. Abajo de todo: Developer settings → Personal access tokens → Tokens (classic).

3. Generate new token → Generate new token (classic).

4. Poné un nombre (ej: mcp-server) y una expiración (ej: 30 días).

5. Marcá los scopes:

6. Generate token y copialo (empieza con ghp_). GitHub no lo vuelve a mostrar.

⚠️ Nunca subas el token al repositorio. Si se sube por error, revocalo inmediatamente desde la misma pantalla.

2. Configurar .env

cp .env.example .env

Editá .env:

GITHUB_TOKEN=ghp_tu_token_real
LOG_LEVEL=info

.env está en .gitignore, así que no se commitea.

3. Configurar el MCP server en VS Code

El server se ejecuta con node dist/server.js (por eso hay que hacer npm run build antes). El token se lee del .env automáticamente.

Opción A – Extensión Claude Code (recomendada)

El repo ya incluye .mcp.json en la raíz:

{
  "mcpServers": {
    "github-mcp": {
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}

1. Instalá la extensión Claude Code desde el Marketplace de VS Code e iniciá sesión.

2. Abrí la carpeta del proyecto en VS Code (File → Open Folder).

3. Abrí el panel de Claude Code. La primera vez te pide aprobar el server github-mcp del proyecto: aceptá.

4. Escribí /mcp en el chat para verificar que github-mcp aparece conectado con sus 8 tools.

Alternativa por terminal (registra el server con ruta absoluta): claude mcp add github-mcp -- node /ruta/completa/github-mcp-server/dist/server.js

Opción B – GitHub Copilot (modo Agent) con modelo Claude

El repo ya incluye .vscode/mcp.json:

{
  "servers": {
    "github-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/server.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

1. Abrí .vscode/mcp.json y hacé clic en Start sobre github-mcp (o Ctrl+Shift+P → MCP: List Servers → Start).

2. Abrí el chat de Copilot, cambiá a modo Agent y elegí un modelo Claude en el selector.

3. En el ícono de herramientas 🛠️ verificá que aparecen los tools de github-mcp.

4. Verificar con MCP Inspector (debugging)

npm run build
npm run inspector

Se abre una página en el navegador. Clic en Connect → pestaña Tools → List Tools. Podés ejecutar cada tool a mano y ver la respuesta exacta que recibiría el LLM.

Tools

Todos los parámetros owner son opcionales: si no se indican se usa el usuario dueño del token.

1. create_repository

Crea un repositorio nuevo en la cuenta autenticada (con README inicial).

Prompt de ejemplo: "Creá un repositorio privado llamado api-turnos con la descripción 'API de turnos para clínicas'."

2. list_repositories

Lista los repositorios del usuario autenticado.

Prompt de ejemplo: "Mostrame mis últimos 5 repositorios actualizados."

3. create_issue

Abre un issue en un repositorio existente.

Prompt de ejemplo: "En el repo api-turnos abrí un issue 'Validar email en registro' explicando que hoy se aceptan emails sin @."

4. list_issues

Lista los issues abiertos de un repositorio (excluye pull requests).

Prompt de ejemplo: "¿Qué issues abiertos tiene api-turnos?"

5. create_commit

Crea un archivo nuevo o reemplaza el contenido de uno existente, generando un commit.

Prompt de ejemplo: "En api-turnos creá CONTRIBUTING.md con tres reglas para contribuir y commitealo con el mensaje 'docs: agrega guía de contribución'."

Extra credit

Ejemplo de flujo completo (usa todos los tools)

1. "Listá mis repositorios." → list_repositories

2. "Creá un repo público demo-mcp-henry con descripción 'Demo del PI'." → create_repository

3. "Agregale un archivo index.js con un console.log de hola mundo." → create_commit

4. "Abrí un issue 'Agregar tests' en ese repo." → create_issue

5. "¿Qué issues abiertos tiene?" → list_issues

6. "Comentá en el issue #1 'En progreso' y después cerralo." → add_comment_to_issue + close_issue

7. "Mostrame los últimos commits." → list_commits

Manejo de errores

Los logs van a stderr (nunca a stdout, que está reservado para el protocolo MCP) y los tokens se ocultan (ghp_***).

Tests

npm test

27 tests unitarios con Vitest, sin llamadas reales a GitHub (Octokit se mockea con vi.mock()):

• tests/tools.test.ts – schemas de Zod: inputs válidos pasan, inválidos fallan con mensajes claros.

• tests/github.test.ts – operaciones con Octokit mockeado: parámetros enviados, mapeo de respuestas, 401, 404, 422.

• tests/errors.test.ts – transformación de errores, retry con backoff y ocultamiento de tokens.

Otros scripts:

Troubleshooting

Licencia

MIT