MCP GitHub Manager

GitHub Total Manager MCP

  ](https://github.com/PyGithub/PyGithub)  

Un servidor Model Context Protocol (MCP) robusto y escalable para gestionar repositorios de GitHub mediante programación. Construido con Python y FastMCP, proporciona 28 operaciones CRUD completas para issues, etiquetas, milestones, ramas y pull requests a través de una interfaz unificada.

Perfecto para: Desarrolladores, equipos DevOps, pipelines CI/CD y agentes de IA que necesitan automatizar flujos de trabajo de GitHub de forma segura y eficiente.

📋 Tabla de Contenidos

• ✨ Características Principales
• 🛠️ Stack Tecnológico
• 📋 Requisitos Previos
• 🚀 Guía de Instalación
• 🏗️ Descripción de la Arquitectura
• 🧰 Herramientas Disponibles
• ⚙️ Configuración
• 📖 Ejemplos de Uso
• 🆘 Solución de Problemas
• 📜 Licencia

✨ Características Principales

• 28 Herramientas MCP organizadas por categoría (Issues, Etiquetas, Milestones, Ramas, PRs)
• Operaciones CRUD Completas para todas las entidades de GitHub
• Validación Inteligente de colores hexadecimales, fechas ISO8601 y ramas protegidas
• Manejo Robusto de Errores con mensajes específicos y accionables
• Integración MCP Nativa compatible con Claude Desktop, OpenCode y herramientas similares
• API PyGithub Limpia sin dependencias externas complejas
• Listo para Producción con pruebas exhaustivas y protecciones de seguridad

🛠️ Stack Tecnológico

📋 Requisitos Previos

Sistema

• Python 3.8 o superior (3.11+ recomendado)
• Git para clonar el repositorio
• Cuenta de GitHub con repositorio accesible
• macOS/Linux/Windows totalmente soportado

Configuración de GitHub

1. Generar Token de Acceso Personal (PAT)

- Ve a - Haz clic en "Generate new token (classic)" - Selecciona permiso: repo (control total de repositorios) - Copia el token (solo lo verás una vez)

1. Almacenamiento Seguro

- Añádelo al archivo .env en este proyecto - Nunca hagas commit del archivo .env - Utiliza tokens separados para desarrollo/staging/producción

🚀 Guía de Instalación

1. Clonar el Repositorio

git clone https://github.com/AlexAlonsoMontero/mcp-py-github.git
cd mcp-py-github

2. Configurar Entorno Python

# Crear entorno virtual
python3 -m venv .venv

# Activarlo
source .venv/bin/activate
# En Windows: .venv\Scripts\activate

# Verificar activación
which python  # Debe mostrar ruta dentro de .venv

3. Instalar Dependencias

pip install --upgrade pip
pip install -r requirements.txt

Dependencias principales:

• fastmcp — Framework del servidor MCP
• PyGithub — Cliente de API de GitHub
• python-dotenv — Gestión de variables de entorno
• requests — Librería HTTP

4. Configurar Variables de Entorno

cp .env.example .env
# Editar .env con tu token real
nano .env  # macOS/Linux
# o notepad .env  # Windows

Variables requeridas y opcionales:

Archivo .env de ejemplo:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LOG_LEVEL=info
MCP_SERVER_NAME=github-manager

5. Verificar Instalación

python3 -c "
import os
from dotenv import load_dotenv
from github import Github

load_dotenv()
token = os.getenv('GITHUB_TOKEN')
if token:
    gh = Github(token)
    user = gh.get_user()
    print(f'✅ Conectado como: {user.login}')
    print(f'📊 Repositorios: {user.get_repos().totalCount}')
else:
    print('❌ GITHUB_TOKEN no encontrado en .env')
"

6. Iniciar el Servidor MCP

python src/main.py

# Salida esperada:
# 2025-02-08 14:30:45 - INFO - FastMCP Server starting...
# 2025-02-08 14:30:45 - INFO - Connected as: AlexAlonsoMontero
# 2025-02-08 14:30:46 - INFO - Server ready on stdio

🏗️ Descripción de la Arquitectura

Estructura del Proyecto

mcp-py-github/
├── src/
│   └── main.py                    # Servidor MCP (879 líneas, 28 tools)
├── .env.example                   # Plantilla de variables
├── .env                           # Config real (git-ignorado)
├── .gitignore                     # Exclusiones
├── requirements.txt               # Dependencias (87 paquetes)
├── sonar-project.properties       # SonarQube config
└── README.md                      # Este archivo

Flujo de Datos

Cliente MCP (Claude, OpenCode, etc.)
         ↓
    Protocolo MCP (stdio)
         ↓
FastMCP Server (src/main.py)
  • 28 funciones @mcp.tool()
  • Validación inteligente
  • Manejo de errores
         ↓
    Librería PyGithub
         ↓
    API REST de GitHub
  • Repositorios
  • Issues & Comentarios
  • Etiquetas & Milestones
  • Ramas & Referencias
  • Pull Requests

Autenticación y Validación

1. Cargar GITHUB_TOKEN desde .env
2. Inicializar Github(GITHUB_TOKEN) vía PyGithub
3. Verificar token con get_user().login
4. Almacenar gh_user para resolución de repos
5. Cada herramienta usa objeto gh autenticado

Validaciones aplicadas:
• Colores: regex ^[a-fA-F0-9]{6}$
• Fechas: datetime.fromisoformat()
• Ramas: lista de protegidas
• Repositorios: verificación vía API

🧰 Herramientas Disponibles

📌 Herramientas de Consulta (Solo Lectura)

📝 Herramientas de Gestión de Issues

🏷️ Herramientas de Gestión de Etiquetas

🎯 Herramientas de Gestión de Milestones

🌿 Herramientas de Gestión de Ramas

🔀 Herramientas de Pull Requests

⚙️ Configuración

Ramas Protegidas

Por defecto, estas ramas no pueden ser eliminadas (protección de seguridad):

protected_branches = ['main', 'master', 'develop', 'dev', 'staging', 'production']

Para modificar, edita /src/main.py línea 238.

Resolución de Nombres de Repositorio

# Nombre completo (siempre funciona)
owner/repo-name

# Nombre corto (auto-antepone tu usuario)
repo-name  →  AlexAlonsoMontero/repo-name

Permisos del Token

El token debe tener permiso repo:

• Lectura/escritura para issues, PRs, ramas, etiquetas, milestones
• Acceso a commits para flujos avanzados

📖 Ejemplos de Uso

Listar Repositorios

call_tool("list_my_repositories")
# Devuelve:
# AlexAlonsoMontero/mcp-py-github
# AlexAlonsoMontero/otro-proyecto

Crear Issue con Etiquetas

call_tool("create_issue_with_labels",
    repo_name="mcp-py-github",
    title="Añadir soporte para webhooks",
    labels="enhancement,documentation",
    body="## Descripción\n..."
)

Gestionar Etiquetas

# Crear
call_tool("create_label",
    repo_name="mcp-py-github",
    name="prioridad-alta",
    color="FF0000",  # Sin símbolo #
    description="Issues que necesitan atención inmediata"
)

# Actualizar
call_tool("update_label",
    repo_name="mcp-py-github",
    current_name="prioridad-alta",
    color="FF6600"
)

# Listar
call_tool("list_labels", repo_name="mcp-py-github")

Crear Milestone

call_tool("create_milestone",
    repo_name="mcp-py-github",
    title="v2.0 - Integración MCP",
    description="Integración completa",
    due_on="2025-06-30",
    state="open"
)

Crear y Eliminar Rama

# Crear
call_tool("create_branch",
    repo_name="mcp-py-github",
    branch_name="feature/webhooks",
    base_branch="main"
)

# Eliminar (seguro - ramas protegidas bloqueadas)
call_tool("delete_branch",
    repo_name="mcp-py-github",
    branch_name="feature/webhooks"
)

Buscar y Actualizar Issues

# Buscar
call_tool("search_issue",
    repo_name="mcp-py-github",
    query="webhook"
)

# Actualizar (título, estado, etiquetas)
call_tool("update_issue",
    repo_name="mcp-py-github",
    issue_number=42,
    title="[En Progreso] Añadir soporte",
    state="open",
    labels=["enhancement", "in-progress"]
)

# Asignar a un milestone
call_tool("update_issue",
    repo_name="mcp-py-github",
    issue_number=42,
    milestone_number=3  # Asigna a milestone #3 (ej: v2.0)
)

Asignar Issues

call_tool("assign_issue",
    repo_name="mcp-py-github",
    issue_number=42,
    assignees="AlexAlonsoMontero,otro-desarrollador"
)

Crear Pull Request

call_tool("create_pull_request",
    repo_name="mcp-py-github",
    title="feat: Añadir soporte para webhooks",
    head="feature/webhooks",
    base="main",
    body="## Cambios\n- Endpoint de webhook\n- Dispatcher de eventos\n\nFix #42"
)

Buscar Issues por Etiqueta

call_tool("search_issues_by_label",
    repo_name="mcp-py-github",
    labels="bug,prioridad-alta",  # AND logic
    state="open"
)

Cerrar Issues

call_tool("close_issue",
    repo_name="mcp-py-github",
    issue_number=42
)

🆘 Solución de Problemas

GITHUB_TOKEN no encontrado

Síntoma: Error de autenticación

Solución:

# 1. Verificar que .env existe
ls -la .env

# 2. Verificar token configurado
cat .env | grep GITHUB_TOKEN

# 3. Generar nuevo token si es necesario
# https://github.com/settings/tokens

Conexión rechazada o Error 401

Síntoma: No puede conectarse a GitHub API

Soluciones:

# 1. Verificar token válido (expirados son comunes)
python3 -c "
from github import Github
import os
from dotenv import load_dotenv

load_dotenv()
gh = Github(os.getenv('GITHUB_TOKEN'))
try:
    print(f'Usuario: {gh.get_user().login}')
except Exception as e:
    print(f'Error: {e}')
"

# 2. Verificar permisos: debe tener 'repo' scope
# 3. Si usas 2FA, puede afectar la autenticación

Rama 'main' no existe

Solución:

# Listar ramas existentes
call_tool("list_branches", repo_name="tu-repo")

# Usar la rama base correcta
call_tool("create_branch",
    repo_name="tu-repo",
    branch_name="feature/xyz",
    base_branch="master"  # Ajusta según resultado anterior
)

Etiqueta ya existe

Solución:

# Actualizar en lugar de crear
call_tool("update_label",
    repo_name="tu-repo",
    current_name="bug",
    color="FF0000"
)

Error de permisos (403)

Soluciones:

1. Token debe tener permiso repo
2. Usuario debe tener acceso de escritura al repositorio
3. Regenerar token si los permisos cambiaron

Color no es hexadecimal válido

Solución:

# Color: 6 dígitos hexadecimales SIN #
✅ FF0000  (rojo)
✅ 00FF00  (verde)
✅ aabbcc  (minúsculas ok)

❌ #FF0000  (no incluyas #)
❌ FF00    (muy corto)
❌ GGGGGG  (no es hex)

# Colores comunes:
Rojo:    FF0000
Verde:   00FF00
Azul:    0000FF
Amarillo:FFFF00
Naranja: FF8000
Púrpura: 8000FF

Fecha no es ISO8601 válida

Solución:

# Formato: YYYY-MM-DD
✅ 2025-06-30
✅ 2025-12-31

❌ 30/06/2025  (DD/MM/YYYY)
❌ 06-30-2025  (MM-DD/YYYY)

# Obtener fecha hoy:
python3 -c "from datetime import datetime; print(datetime.now().strftime('%Y-%m-%d'))"

📊 Estadísticas del Proyecto

• Líneas de Código: 879 (src/main.py)
• Herramientas MCP: 28 funciones decoradas
• Funciones Auxiliares: 6 (validación/formato)
• Dependencias: 87 paquetes
• Compatibilidad: Python 3.8+
• Tests Manuales: 37 operaciones CRUD, 99% éxito

📜 Licencia

Licencia MIT - Ver archivo LICENSE para detalles

🔗 Enlaces Útiles

• Issues de GitHub: Reporta bugs o sugiere features
• Documentación: README.md y docstrings en src/main.py
• GitHub Docs:

📝 Historial de Versiones

v1.0.0 (2025-02-08)

Lanzamiento Inicial

• 28 herramientas de gestión de GitHub
• Operaciones CRUD completas
• Validación y manejo de errores robusto
• Servidor MCP listo para producción
• Documentación integral
• Pruebas manuales del 99%

Construido con ❤️ por Alex Alonso Montero

Última actualización: 2025-02-08