PyGithub MCP Server

Interactúa con la API de GitHub usando PyGithub para gestionar repositorios, issues y pull requests.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de PyGithub

Un servidor de Model Context Protocol que proporciona herramientas para interactuar con la API de GitHub a través de PyGithub. Este servidor permite a los asistentes de IA realizar operaciones de GitHub como gestionar issues, repositorios y pull requests.

Características

  • Arquitectura de herramientas modular:

    • Grupos de herramientas configurables que pueden habilitarse/deshabilitarse
    • Organización por dominio específico (issues, repositorios, etc.)
    • Configuración flexible mediante archivo o variables de entorno
    • Separación clara de responsabilidades con diseño modular
    • Extensión sencilla con patrones consistentes

  • Gestión completa de issues de GitHub:

    • Crear y actualizar issues
    • Obtener detalles de issues y listar issues de repositorios
    • Añadir, listar, actualizar y eliminar comentarios
    • Gestionar etiquetas de issues
    • Manejar asignados e hitos

  • Manejo inteligente de parámetros:

    • Construcción dinámica de kwargs para parámetros opcionales
    • Conversión de tipos adecuada para objetos de GitHub
    • Validación de todos los parámetros de entrada
    • Mensajes de error claros para entradas no válidas

  • Implementación robusta:

    • Interacciones con la API de GitHub orientadas a objetos mediante PyGithub
    • Gestión centralizada del cliente de GitHub
    • Manejo adecuado de errores y limitación de velocidad
    • Abstracción limpia de la API a través de herramientas MCP
    • Soporte integral de paginación
    • Registro detallado para depuración

Documentación

Hay guías completas disponibles en el directorio docs/guides:

  • error-handling.md: Tipos de error, patrones de manejo y mejores prácticas
  • security.md: Autenticación, control de acceso y seguridad de contenido
  • tool-reference.md: Documentación detallada de herramientas con ejemplos

Consulta estas guías para obtener información detallada sobre el uso del Servidor MCP de PyGithub.

Ejemplos de uso

Operaciones con issues

  1. Crear un issue
{
  "owner": "username",
  "repo": "repository",
  "title": "Issue Title",
  "body": "Issue description",
  "assignees": ["username1", "username2"],
  "labels": ["bug", "help wanted"],
  "milestone": 1
}
  1. Obtener detalles de un issue
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1
}
  1. Actualizar un issue
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "title": "Updated Title",
  "body": "Updated description",
  "state": "closed",
  "labels": ["bug", "wontfix"]
}

Operaciones con comentarios

  1. Añadir un comentario
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "body": "This is a comment"
}
  1. Listar comentarios
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "per_page": 10
}
  1. Actualizar un comentario
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "comment_id": 123456789,
  "body": "Updated comment text"
}

Operaciones con etiquetas

  1. Añadir etiquetas
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "labels": ["enhancement", "help wanted"]
}
  1. Eliminar una etiqueta
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "label": "enhancement"
}

Todas las operaciones manejan los parámetros opcionales de forma inteligente:

  • Solo incluye los parámetros proporcionados en las llamadas a la API
  • Convierte tipos primitivos a objetos de GitHub (por ejemplo, número de hito a objeto Milestone)
  • Proporciona mensajes de error claros para parámetros no válidos
  • Maneja la paginación automáticamente cuando corresponde

Instalación

  1. Crear y activar un entorno virtual:
uv venv
source .venv/bin/activate
  1. Instalar dependencias:
uv pip install -e .

Configuración

Configuración básica

Añade el servidor a tu configuración de MCP (por ejemplo, claude_desktop_config.json o cline_mcp_settings.json):

{
  "mcpServers": {
    "github": {
      "command": "/path/to/repo/.venv/bin/python",
      "args": ["-m", "pygithub_mcp_server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Configuración de grupos de herramientas

El servidor admite habilitar o deshabilitar selectivamente grupos de herramientas mediante la configuración. Puedes configurarlo de dos maneras:

1. Archivo de configuración

Crea un archivo de configuración JSON (por ejemplo, pygithub_mcp_config.json):

{
  "tool_groups": {
    "issues": {"enabled": true},
    "repositories": {"enabled": true},
    "pull_requests": {"enabled": false},
    "discussions": {"enabled": false},
    "search": {"enabled": true}
  }
}

Luego especifica este archivo en tu entorno:

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

2. Variables de entorno

Alternativamente, usa variables de entorno para configurar los grupos de herramientas:

export PYGITHUB_ENABLE_ISSUES=true
export PYGITHUB_ENABLE_REPOSITORIES=true
export PYGITHUB_ENABLE_PULL_REQUESTS=false

Por defecto, solo el grupo de herramientas issues está habilitado. Consulta README.config.md para opciones de configuración más detalladas.

Desarrollo

Pruebas

El proyecto incluye un conjunto de pruebas completo:

# Run all tests
pytest

# Run tests with coverage report
pytest --cov

# Run specific test file
pytest tests/test_operations/test_issues.py

# Run tests matching a pattern
pytest -k "test_create_issue"

Nota: Muchas pruebas están fallando actualmente y están bajo investigación. Es un problema conocido que se está abordando activamente.

Pruebas con MCP Inspector

Prueba las herramientas MCP durante el desarrollo usando el MCP Inspector:

source .venv/bin/activate  # Ensure venv is activated
npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub-mcp-server

Usa la interfaz web del MCP Inspector para:

  • Experimentar con las herramientas disponibles
  • Probar con repositorios reales de GitHub
  • Verificar casos de éxito y error
  • Documentar payloads que funcionan

Estructura del proyecto

tests/
├── unit/                # Fast tests without external dependencies
│   ├── config/          # Configuration tests
│   ├── tools/           # Tool registration tests
│   └── ...              # Other unit tests
└── integration/         # Tests with real GitHub API
    ├── issues/          # Issue tools tests
    └── ...              # Other integration tests

src/
└── pygithub_mcp_server/
    ├── __init__.py
    ├── __main__.py
    ├── server.py        # Server factory (create_server)
    ├── version.py
    ├── config/          # Configuration system
    │   ├── __init__.py
    │   └── settings.py  # Configuration management
    ├── tools/           # Modular tool system
    │   ├── __init__.py  # Tool registration framework
    │   └── issues/      # Issue tools
    │       ├── __init__.py
    │       └── tools.py # Issue tool implementations
    ├── client/          # GitHub client functionality
    │   ├── __init__.py
    │   ├── client.py    # Core GitHub client
    │   └── rate_limit.py # Rate limit handling
    ├── converters/      # Data transformation
    │   ├── __init__.py
    │   ├── parameters.py # Parameter formatting
    │   ├── responses.py # Response formatting
    │   ├── common/      # Common converters
    │   ├── issues/      # Issue-related converters
    │   ├── repositories/ # Repository converters
    │   └── users/       # User-related converters
    ├── errors/          # Error handling
    │   ├── __init__.py
    │   └── exceptions.py # Custom exceptions
    ├── operations/      # GitHub operations
    │   ├── __init__.py
    │   └── issues.py
    ├── schemas/         # Data models
    │   ├── __init__.py
    │   ├── base.py
    │   ├── issues.py
    │   └── ...
    └── utils/           # General utilities
        ├── __init__.py
        └── environment.py # Environment utilities

Solución de problemas

  1. El servidor no se inicia:

    • Verifica la ruta de Python del venv en la configuración de MCP
    • Asegúrate de que todos los requisitos estén instalados en el venv
    • Comprueba que GITHUB_PERSONAL_ACCESS_TOKEN esté configurado y sea válido

  2. Errores de compilación:

    • Usa la bandera --no-build-isolation con uv build
    • Asegúrate de usar Python 3.10+
    • Verifica que todas las dependencias estén instaladas

  3. Errores de la API de GitHub:

    • Comprueba los permisos y la validez del token
    • Revisa pygithub_mcp_server.log para obtener trazas de error detalladas
    • Verifica que no se hayan superado los límites de velocidad

Dependencias

  • Python 3.10+
  • SDK de Python de MCP
  • Pydantic
  • PyGithub
  • Gestor de paquetes UV

Licencia

MIT