github-projects-mcp

A Model Context Protocol (MCP) server that brings full GitHub Projects v2 (Kanban board) support to Claude Desktop — powered by the GitHub GraphQL API.

The official GitHub MCP connector only covers the REST API, which has no access to GitHub Projects v2. This server fills that gap by exposing five GraphQL-backed tools that let Claude manage your Kanban boards, create issues, and move cards — all without leaving the conversation.

Features

• 📋 List board items — see all issues/PRs and their current column status
• 🔀 Move Kanban items — drag cards between columns (Todo → In Progress → Done) programmatically
• 🔍 Get project metadata — inspect fields, status options, and project structure
• ✍️ Create issues — open new issues directly from Claude
• ➕ Add issues to a project — link existing issues to any project board

Requirements

• Node.js v18 or higher
• Claude Desktop
• A GitHub Personal Access Token (classic) with the following scopes:
  • repo
  • project

Installation

1. Clone the repository

git clone https://github.com/johnmikepty/github-projects-mcp.git
cd github-projects-mcp

2. Install dependencies and build

npm install
npm run build

3. Generate a GitHub Token

Go to https://github.com/settings/tokens → Generate new token (classic)

Required scopes:

| Scope | Reason | |---|---| | repo | Read issues and repository data | | project | Read and write Projects v2 boards |

4. Register in Claude Desktop

Edit your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following entry inside mcpServers:

{
  "mcpServers": {
    "github-projects": {
      "command": "node",
      "args": ["C:\\path\\to\\github-projects-mcp\\dist\\index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Note: On Windows use double backslashes (\\) in the path.

5. Restart Claude Desktop

Close and reopen Claude Desktop completely. You should see github-projects listed under connected MCP servers in Settings → Connectors.

Tools

get_project

Get project metadata including all fields and available status column options.

| Parameter | Type | Description | |---|---|---| | owner | string | GitHub username or organization | | projectNumber | number | Project number (from the URL) |

list_project_items

List all issues and PRs on the board with their current status column.

| Parameter | Type | Description | |---|---|---| | owner | string | GitHub username or organization | | projectNumber | number | Project number |

move_project_item

Move an issue or PR to a different status column on the Kanban board.

| Parameter | Type | Description | |---|---|---| | owner | string | GitHub username or organization | | projectNumber | number | Project number | | issueNumber | number | Issue or PR number | | targetStatus | string | Target column name e.g. Todo, In Progress, Done |

create_issue

Create a new GitHub issue in any repository.

| Parameter | Type | Description | |---|---|---| | owner | string | GitHub username or organization | | repo | string | Repository name | | title | string | Issue title | | body | string (optional) | Issue body (Markdown supported) |

add_issue_to_project

Add an existing issue to a project board by its GraphQL node ID.

| Parameter | Type | Description | |---|---|---| | owner | string | GitHub username or organization | | projectNumber | number | Project number | | issueNodeId | string | Issue node ID (starts with I_kw...) |

Usage Examples

Once registered, you can ask Claude naturally:

List all items in project 9 of johnmikepty

Move issue #15 to Done in project 9 of johnmikepty

Create an issue titled "Fix login bug" in johnmikepty/my-app

What issues are still in Backlog in project 9?

Development

Run without building (uses tsx for on-the-fly TypeScript execution):

GITHUB_TOKEN=ghp_your_token npm run dev

Build for production:

npm run build
npm start

Project Structure

github-projects-mcp/
├── src/
│   ├── index.ts              → MCP server entry point, tool definitions
│   ├── graphql.ts            → Reusable GitHub GraphQL client
│   └── tools/
│       ├── get-project.ts    → Fetch project metadata
│       ├── list-items.ts     → List board items with status
│       ├── move-item.ts      → Move item to a status column
│       ├── create-issue.ts   → Create a new issue
│       └── add-to-project.ts → Add issue to a project board
├── dist/                     → Compiled output (generated by build)
├── package.json
├── tsconfig.json
└── README.md

Why This Exists

The official GitHub MCP connector uses the REST API, which does not support GitHub Projects v2. Moving Kanban cards requires the GraphQL API (updateProjectV2ItemFieldValue mutation). This server bridges that gap so Claude can manage your entire project workflow — creating issues, tracking progress, and closing cards — without ever leaving the chat.

Contributing

Pull requests are welcome. If you'd like to add new tools (e.g., filtering by assignee, milestone support, or org-level projects), feel free to open an issue or submit a PR.

License

MIT