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

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