Skip to main content
Glama
deenesjakoruzh
kmosoti

github-projects

by kmosoti
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

github-projects

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.

Architecture

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 unions

  • The 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.

Setup

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 v2

Tokens 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 stdio

Using it from Claude Code and Codex

From 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-mcp

Plugin 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.

Tools

Tool

Purpose

list_projects

List boards for a user/org (optional search)

get_project

Board by owner + number

list_fields

Fields incl. single-select options and iterations

list_items

Items with content + field values, optionally evaluated through a saved-view filter query

create_project / update_project

Create board; edit title/readme/visibility/closed

add_item

Add an issue/PR by URL

add_draft_issue

Add a draft issue

update_field_value

Set a field; values are strings coerced by field type — single-select and iteration match by name (Status → "Done")

clear_field_value

Clear a field

archive_item / delete_item

Archive or remove an item

plan_project / apply_project

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

sprint_board

Status-column view of one iteration (or all items + unplanned bucket)

epic_breakdown

Per-epic completion rollup from the native sub-issue hierarchy

list_views

Saved views with name, layout, filter, and ordered visible fields

post_status_update / list_status_updates

The project's long-horizon context trail

This server cannot be installed

-
license - not tested
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • GitHub

    Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.

  • Threadminder

    Persistent context for Claude. Your AI always knows your projects and next actions across sessions.

  • Hint-Services-obsidian-github-mcp

    Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kmosoti/github-projects'

If you have feedback or need assistance with the MCP directory API, please join our Discord server