GitHub Projects V2

Gestiona GitHub Projects V2 usando la API GraphQL de GitHub.

Documentación

Servidor MCP de GitHub Projects V2

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para gestionar GitHub Projects V2 a través de Claude y otros clientes MCP. Este servidor utiliza la API GraphQL de GitHub para interactuar con GitHub Projects V2.

Características

Listar y ver GitHub Projects V2 para usuarios y organizaciones
Obtener campos y elementos de proyectos (issues, PRs, borradores de issues)
Crear issues y añadirlos a proyectos
Crear borradores de issues directamente en proyectos
Actualizar valores de campos de elementos de proyectos
Eliminar elementos de proyectos

Uso

Este servidor puede utilizarse con cualquier cliente MCP, como Claude Desktop. Añádelo a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json).

Opción 1: Usar el paquete publicado

Aquí tienes un ejemplo de configuración usando uvx como ejecutor de comandos:

{
  "mcpServers": {
    "github-projects": {
      "command": "uvx",
      "args": [
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Asegúrate de reemplazar your_pat_here con tu Token de Acceso Personal de GitHub real.

Opción 2: Desde el código fuente

Para ejecutar el proyecto directamente desde el código fuente, sigue estos pasos:

Configuración

Clona el repositorio:

git clone git@github.com:Arclio/github-projects-mcp.git
cd github-projects-mcp

Crea y activa un entorno virtual:
```
uv venv
source venv/bin/activate
```
Instala las dependencias:
```
uv pip install -e .
```
Establece tu token de GitHub como variable de entorno:

Crea un Token de Acceso Personal de GitHub y otórgale los permisos necesarios. Los permisos requeridos son: repo, project y read:org.

Añade el token a tu archivo .env después de ejecutar este comando:
```
cp .env.example .env
```
Luego añade lo siguiente a tu archivo .env:
```
export GITHUB_TOKEN=your_personal_access_token
```

Uso desde el código fuente

Cuando se utiliza desde el código fuente, configura tu cliente MCP de la siguiente manera:

{
  "mcpServers": {
    "github-projects": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/github-projects-mcp",
        "run",
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Asegúrate de reemplazar /path/to/github-projects-mcp y your_pat_here con la ruta real de tu repositorio y tu Token de Acceso Personal de GitHub.

Herramientas disponibles

list_projects: Lista GitHub Projects V2 para una organización o usuario determinados
get_project_fields: Obtiene los campos disponibles en un GitHub Project V2
get_project_items: Obtiene los elementos de un GitHub Project V2 (admite filtrado por estado o campos personalizados de selección única)
create_issue: Crea un nuevo issue de GitHub
add_issue_to_project: Añade un issue existente de GitHub a un Project V2
update_project_item_field: Actualiza el valor de un campo para un elemento de proyecto
create_draft_issue: Crea un borrador de issue directamente en un GitHub Project V2
delete_project_item: Elimina un elemento de un GitHub Project V2

Consulta la documentación de las herramientas en el código del servidor para obtener información detallada sobre su uso.

Desarrollo

El proyecto está estructurado de la siguiente manera:

src/github_projects_mcp/: Directorio principal del paquete
- server.py: Implementación del servidor MCP con definiciones de herramientas
- github_client.py: Cliente GraphQL para interacciones con la API de GitHub

Para contribuir, asegúrate de:

Añadir un manejo de errores adecuado para todas las operaciones GraphQL
Añadir anotaciones de tipo para todas las funciones y parámetros
Actualizar la documentación al añadir nuevas herramientas o características