Provides tools for managing GitHub Projects v2 boards, including listing projects, fields, items, and views; creating and updating projects; adding issues/PRs and draft items; setting and clearing field values; archiving/deleting items; reconciling desired board state; and generating sprint and epic-breakdown views.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@github-projects What's on the sprint board for project 42?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A plugin for Claude Code and Codex: Pydantic v2 models, PEP 544
protocols, and an MCP server for managing GitHub Projects v2 boards
(e.g. github.com/users/<owner>/projects/<n>) — with first-class support
for the draft HTTP QUERY method.
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 unionsThe MCP layer depends only on the ProjectsBackend protocol, so backends
are swappable and tests substitute fakes structurally.
QueryClient sends QUERY optimistically, records Accept-Query
advertisements, retries once on transport errors (QUERY is safe and
idempotent), and permanently falls back to POST per origin on 405/501 —
so it works against GitHub today and upgrades itself when GitHub ships
QUERY support.
Related MCP server: GitHub Project MCP Server
The primary runtime is CPython 3.14.7 free-threaded (3.14.7t). It also
requires the gh CLI to be authenticated with the project scope:
gh auth refresh -s project # grants read + write for Projects v2Tokens are resolved from GITHUB_TOKEN / GH_TOKEN, else gh auth token.
uv sync
uv run pytest # 32 tests
uv run gh-projects-mcp # run the server on stdioFrom the repository root:
# 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-mcpPlugin manifests live in .claude-plugin/plugin.json (with the MCP server
declared via ${CLAUDE_PLUGIN_ROOT}) and .codex-plugin/plugin.json; a
usage skill for both hosts is in skills/github-projects/SKILL.md.
Tool | Purpose |
| List boards for a user/org (optional search) |
| Board by owner + number |
| Fields incl. single-select options and iterations |
| Items with content + field values, optionally evaluated through a saved-view filter query |
| Create board; edit title/readme/visibility/closed |
| Add an issue/PR by URL |
| Add a draft issue |
| Set a field; values are strings coerced by field type — single-select and iteration match by name ( |
| Clear a field |
| Archive or remove an item |
| Idempotent desired-state reconciliation: fields and option aliases, semantically verified leaf/container views, ordered columns, explicit retirements, item metadata, epic/sub-issue hierarchy, native issue dependencies, and legacy dependency-prose cleanup |
| Status-column view of one iteration (or all items + unplanned bucket) |
| Per-epic completion rollup from the native sub-issue hierarchy |
| Saved views with name, layout, filter, and ordered visible fields |
| The project's long-horizon context trail |
This server cannot be deployed
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Access the GitHub API, enabling file operations, repository management, search functionality, and…
