🐙 Servidor MCP para GitHub

Un servidor completo de Model Context Protocol (MCP) para interactuar con GitHub. Permite gestionar repositorios, issues, pull requests, branches, commits, releases, webhooks y mucho más desde Cursor o Claude Desktop.

✨ Características Principales

• ✅ Gestión completa de repositorios (listar, buscar, obtener detalles)
• ✅ Pull Requests (crear, mergear, cerrar, actualizar, reviews)
• ✅ Issues (crear, actualizar, cerrar, comentarios)
• ✅ Búsqueda avanzada (código, issues, usuarios, commits)
• ✅ Gestión de commits (obtener detalles, listar, comparar)
• ✅ Releases y Tags (crear, listar, obtener detalles)
• ✅ Webhooks (crear, actualizar, eliminar, ping)
• ✅ Protección de ramas (configurar reglas de protección)
• ✅ Multiplataforma (macOS, Linux, Windows)

🚀 Instalación Rápida

Requisitos

• Node.js 18+ instalado
• npm o pnpm
• Personal Access Token de GitHub con permisos repo

Instalación desde npm

npm install -g mcp-github-server
# o con pnpm:
pnpm add -g mcp-github-server

Instalación desde código fuente

git clone https://github.com/pblarismendi/mcp-github-server.git
cd mcp-github-server
npm install
npm run build

🔑 Configuración

1. Obtener un Personal Access Token de GitHub

1. Ve a GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
2. Haz clic en "Generate new token (classic)"
3. Dale un nombre descriptivo (ej: "MCP Server")
4. Selecciona los scopes:
   • ✅ repo (Full control of private repositories)
   • ✅ read:org (opcional, para organizaciones)
5. Haz clic en "Generate token"
6. Copia el token inmediatamente (solo se muestra una vez)

2. Configurar en Cursor/Claude Desktop

Cursor

Ubicación: ~/.cursor/mcp.json o .cursor/mcp.json en tu workspace

Configuración - Método 1: Con npx (Recomendado - Más Simple)

Este método no requiere encontrar rutas absolutas ni instalar globalmente:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-github-server"],
      "env": {
        "GITHUB_TOKEN": "tu_token_aqui"
      }
    }
  }
}

Configuración - Método 2: Con ruta absoluta

Si prefieres usar una instalación global, usa la ruta absoluta:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["RUTA_ABSOLUTA/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "tu_token_aqui"
      }
    }
  }
}

Ejemplos de rutas:

• macOS: "/Users/tu_usuario/.npm-global/lib/node_modules/mcp-github-server/dist/index.js"
• Linux: "/usr/local/lib/node_modules/mcp-github-server/dist/index.js"
• Windows: "C:\\Users\\tu_usuario\\AppData\\Roaming\\npm\\node_modules\\mcp-github-server\\dist\\index.js"

Claude Desktop

Ubicación:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuración: (igual que Cursor)

3. Encontrar la ruta de instalación (Solo si usas Método 2)

Si instalaste globalmente con npm/pnpm y necesitas la ruta absoluta, encuentra la ruta con:

npm list -g mcp-github-server
# o
pnpm list -g mcp-github-server

O busca el ejecutable:

# macOS/Linux:
which mcp-github
which mcp-github-server

# Windows (PowerShell/CMD):
where mcp-github
where mcp-github-server

Nota: Si where mcp-github-server no encuentra nada en Windows, usa el Método 1 con npx que no requiere encontrar rutas.

💻 Uso Básico

Una vez configurado, el servidor MCP estará disponible en Cursor o Claude Desktop. Puedes usar comandos como:

• "Lista mis repositorios"
• "Muéstrame los PRs abiertos del repositorio X"
• "Crea un issue en el repositorio Y"
• "Busca código que contenga 'function calculate'"

🛠️ Herramientas Disponibles

Repositorios

• list_repositories - Lista repositorios con filtros
• get_repository - Obtiene detalles de un repositorio
• search_repositories - Busca repositorios en GitHub

Pull Requests

• list_pull_requests - Lista PRs
• create_pull_request - Crea un PR
• get_pull_request - Obtiene detalles de un PR
• merge_pull_request - Mergea un PR (merge, squash, rebase)
• close_pull_request - Cierra un PR
• update_pull_request - Actualiza un PR
• add_pull_request_review - Agrega una review
• list_pull_request_reviews - Lista reviews de un PR

Issues

• list_issues - Lista issues
• create_issue - Crea un issue
• update_issue - Actualiza un issue
• close_issue - Cierra un issue
• add_issue_comment - Agrega un comentario
• list_issue_comments - Lista comentarios

Búsqueda

• search_code - Busca código en repositorios
• search_issues - Busca issues y PRs
• search_users - Busca usuarios
• search_commits - Busca commits

Commits

• get_commit - Obtiene detalles de un commit
• list_commits - Lista commits con filtros
• compare_commits - Compara commits o branches

Releases y Tags

• list_releases - Lista releases
• get_release - Obtiene detalles de un release
• create_release - Crea un release
• list_tags - Lista tags
• create_tag - Crea un tag

Webhooks

• list_webhooks - Lista webhooks
• get_webhook - Obtiene detalles de un webhook
• create_webhook - Crea un webhook
• update_webhook - Actualiza un webhook
• delete_webhook - Elimina un webhook
• ping_webhook - Hace ping a un webhook

Branches

• list_branches - Lista branches
• protect_branch - Protege una rama

Otros

• get_user_info - Obtiene información del usuario
• get_file_content - Lee archivos o directorios

🐛 Solución de Problemas

Error: "GITHUB_TOKEN no está configurado"

• Verifica que el token esté en la configuración de Cursor/Claude Desktop
• Asegúrate de que no haya espacios antes o después del token

Error: "Bad credentials"

• Tu token puede haber expirado
• Genera un nuevo token en GitHub y actualiza la configuración

El servidor no se conecta

• Verifica que la ruta al archivo dist/index.js sea correcta y absoluta (si usas Método 2)
• Asegúrate de haber instalado el paquete correctamente
• Revisa los logs de Cursor/Claude Desktop para ver errores específicos
• Solución rápida: Usa el Método 1 con npx que no requiere rutas absolutas

Problemas Específicos de Windows

El ejecutable no se encuentra después de instalar globalmente

Problema: Después de ejecutar npm install -g mcp-github-server, el comando where mcp-github-server no encuentra nada.

Solución 1 (Recomendada): Usa npx en lugar de buscar el ejecutable:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-github-server"],
      "env": {
        "GITHUB_TOKEN": "tu_token_aqui"
      }
    }
  }
}

Solución 2: Encuentra la ruta manualmente:

1. Ejecuta en PowerShell o CMD:

   npm list -g mcp-github-server

2. Busca la ruta en la salida (normalmente algo como):

   C:\Users\tu_usuario\AppData\Roaming\npm\node_modules\mcp-github-server

3. Usa la ruta completa en la configuración:

   {
     "mcpServers": {
       "github": {
         "command": "node",
         "args": ["C:\\Users\\tu_usuario\\AppData\\Roaming\\npm\\node_modules\\mcp-github-server\\dist\\index.js"],
         "env": {
           "GITHUB_TOKEN": "tu_token_aqui"
         }
       }
     }
   }

El archivo .cmd no se creó después de la instalación global

Problema: Windows necesita archivos .cmd o .exe pero npm no los creó automáticamente.

Solución: Esto es normal y no es un problema. Puedes usar cualquiera de estos métodos:

1. Usar npx (más simple):

   {
     "command": "npx",
     "args": ["-y", "mcp-github-server"]
   }

2. Usar node directamente con la ruta:

   {
     "command": "node",
     "args": ["RUTA_COMPLETA/dist/index.js"]
   }

Problemas con rutas en Windows

• Usa barras normales / o dobles backslashes \\
• Ejemplo: "C:\\Users\\Usuario\\...\\dist\\index.js" o "C:/Users/Usuario/.../dist/index.js"
• Recomendación: Usa npx para evitar problemas con rutas

📚 Documentación Completa

Para más información sobre desarrollo, contribución, testing y características avanzadas, consulta:

• README.DEV.md - Documentación completa para desarrolladores
• GitHub Repository - Código fuente y issues

💖 Sponsor este Proyecto

Si este proyecto te resulta útil, considera patrocinarme:

Tu apoyo ayuda a mantener y mejorar este proyecto. ¡Gracias! 🙏

👨‍💻 Desarrollador

Desarrollado con ❤️ por Pablo Arismendi

• GitHub: @pblarismendi

📝 Licencia

MIT

📞 Soporte

Si encuentras algún problema o tienes preguntas:

• Abre un issue en GitHub
• Consulta la documentación completa para desarrolladores