gh-board-mcp

MCP server for managing GitHub Projects v2 as a personal kanban board. Create activities (draft items), move them between columns, track priority — without linking to real issues.

Requirements

• Node.js >= 18
• A GitHub Personal Access Token with the project scope (fine-grained: Projects read/write)

Usage

The package is published on npm — any MCP client can launch it with npx gh-board-mcp:

GITHUB_TOKEN=ghp_xxx npx -y gh-board-mcp

Claude Code

Register it globally (available in all projects):

claude mcp add gh-board-mcp -s user -e GITHUB_TOKEN=ghp_xxx -- npx -y gh-board-mcp

• -s user → global config (all projects); use -s project to scope it to a single repo.
• -e GITHUB_TOKEN=... sets the token env var; the -- separates the server command.
• Verify with claude mcp list → gh-board-mcp should show Connected.

OpenCode

Add it to the global config at ~/.config/opencode/opencode.json (or .jsonc):

{
  "mcp": {
    "gh-board-mcp": {
      "type": "local",
      "command": ["npx", "-y", "gh-board-mcp"],
      "enabled": true,
      "environment": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

Verify with opencode mcp list → gh-board-mcp should show connected.

Tools

Tool	Description
list_projects	List your GitHub Projects v2 boards
create_project	Create a new board (default Status + Priority fields, opens with a board view)
list_activities	List activities (draft items), filter by status/priority
create_activity	Create an activity with optional status/priority
move_activity	Move an activity to another status (and set priority)
update_activity	Edit an activity's title/description
delete_activity	Delete an activity (permanent)
archive_activity	Archive an activity (hidden from lists, reversible)
unarchive_activity	Restore an archived activity

Status & Priority

• create_project creates a new board with Status = Todo / In Progress / Done, Priority = Urgent / High / Medium / Low, and a board (kanban) view as its default view.
• Boards created from a GitHub template keep their own Status/Priority options — pass values that exist on the board. create_activity, move_activity, and list_activities report the valid options when given an unknown value.
• Custom columns are not supported via the API (configure them in the GitHub UI).

Notes

• Read cap: list_activities and list_projects read up to 100 items / projects in one call; larger boards are truncated.
• Archive ≠ delete: archive_activity hides an item from list_activities but keeps it (restorable via unarchive_activity); delete_activity removes it permanently.
• Eventual consistency: GitHub Projects v2 writes can take a moment to appear in reads — a list_activities immediately after create_activity may briefly miss the new item.
• Create is not atomic: create_activity validates the status/priority options before creating, so a bad option leaves nothing behind; a transient network error mid-create can still leave a draft without its field values.

Development

npm install
npm test
npm run build
npm run dev

License

MIT