Un plugin para Claude Code y Codex: modelos Pydantic v2, protocolos PEP 544
y un servidor MCP para gestionar tableros de GitHub Projects v2
(p. ej. github.com/users/<owner>/projects/<n>) — con soporte de primera clase
para el método HTTP QUERY en fase de borrador.
server.py MCP server (mcp SDK v2, stdio) — 19 tools, structured output
│ depends on
protocols.py ProjectsBackend / GraphQLTransport (runtime-checkable Protocols)
│ implemented by
service.py GitHubProjectsService — GraphQL over the transport,
project-id + field caching, string→typed field-value coercion
graphql.py GraphQL documents (works for both user and org owners)
http.py QueryClient — HTTP QUERY (draft-ietf-httpbis-safe-method-w-body)
with per-origin capability memory and POST fallback
models.py Frozen Pydantic v2 models, __typename-discriminated unionsLa capa MCP depende únicamente del protocolo ProjectsBackend, por lo que
los backends son intercambiables y las pruebas sustituyen el backend por
fakes estructurales.
QueryClient envía QUERY de forma optimista, registra los anuncios
Accept-Query, reintenta una vez ante errores de transporte (QUERY es seguro
e idempotente) y cae permanentemente a POST por origen ante 405/501 — por
lo que funciona con GitHub hoy mismo y se actualiza automáticamente cuando
GitHub implemente soporte para QUERY.
Related MCP server: GitHub Project MCP Server
El entorno de ejecución principal es CPython 3.14.7 free-threaded (3.14.7t).
También requiere que la CLI de gh esté autenticada con el ámbito project:
gh auth refresh -s project # grants read + write for Projects v2Los tokens se resuelven desde GITHUB_TOKEN / GH_TOKEN, o, si no, desde
gh auth token.
uv sync
uv run pytest # 32 tests
uv run gh-projects-mcp # run the server on stdioDesde la raíz del repositorio:
# Claude Code (registered user-wide)
claude mcp add --scope user github-projects -- uv --directory "$PWD" run gh-projects-mcp
# Codex
codex mcp add github-projects -- uv --directory "$PWD" run gh-projects-mcpLos manifiestos de los plugins se encuentran en .claude-plugin/plugin.json
(con el servidor MCP declarado mediante ${CLAUDE_PLUGIN_ROOT}) y
.codex-plugin/plugin.json; una skill de uso para ambos hosts está en
skills/github-projects/SKILL.md.
Herramienta | Propósito |
| Lista tableros de un usuario/org (búsqueda opcional) |
| Tablero por propietario + número |
| Campos, incluidas las opciones de selección única y las iteraciones |
| Elementos con contenido y valores de campo, opcionalmente evaluados mediante una consulta de filtro de vista guardada |
| Crea un tablero; edita título/readme/visibilidad/cerrado |
| Añade un issue/PR por URL |
| Añade un issue en borrador |
| Establece un campo; los valores son cadenas convertidas según el tipo de campo — la selección única y la iteración coinciden por nombre ( |
| Limpia un campo |
| Archiva o elimina un elemento |
| Reconciliación idempotente del estado deseado: campos y alias de opciones, vistas hoja/contenedor verificadas semánticamente, columnas ordenadas, retiradas explícitas, metadatos de elementos, jerarquía de épicas/sub-issues, dependencias de issues nativas y limpieza de prosa de dependencias heredada |
| Vista de columnas de estado de una iteración (o de todos los elementos + el grupo de no planificados) |
| Resumen de progreso por épica a partir de la jerarquía nativa de sub-issues |
| Vistas guardadas con nombre, diseño, filtro y campos visibles ordenados |
| El rastro de contexto a largo plazo del proyecto |
This server cannot be deployed
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
