mcp-server-github-projects

A Model Context Protocol server for the GitHub Projects v2 API — it fills the gap the official GitHub MCP server leaves around project management: views, priorities, dependencies, and metrics, exposed as typed tools an LLM agent can call.

Why it exists: Projects v2 is GraphQL-only and fiddly to drive by hand. Wrapping it in MCP tools lets an agent triage a backlog ("assess priorities for everything in the Sprint view, then re-order it") in one conversation.

How it works

flowchart LR
    A[MCP client<br/>Claude Desktop / Claude Code] -- stdio --> B[mcp-server-github-projects]
    B -- GraphQL --> C[GitHub Projects v2 API]
    B -- REST --> D[GitHub Issues/Repos]

Operations live in src/operations/ (projects, project-items, project-views, priorities, dependencies, metrics), each with typed inputs validated before any API call.

Setup

Note: this package is not on npm — build from source (2 minutes):

git clone https://github.com/TerraCo89/mcp-server-github-projects.git
cd mcp-server-github-projects
npm install && npm run build

Create a GitHub personal access token with project (read/write) and repo (read) scopes.

You can also pin the MCP server to one project by setting:

• GITHUB_PROJECTS_OWNER - org/user login that owns the project
• GITHUB_PROJECTS_PROJECT_NUMBER - the GitHub Projects v2 number
• GITHUB_PROJECTS_PROJECT_ID - optional GraphQL node id override

Use with Claude Desktop / Claude Code

{
  "mcpServers": {
    "github-projects": {
      "command": "node",
      "args": ["/path/to/mcp-server-github-projects/dist/index.js"],
      "env": { "GITHUB_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

Docker alternative: docker build -t mcp/github-projects . then use docker run -i --rm -e GITHUB_TOKEN mcp/github-projects as the command.

Available operations

Projects & items

• createProject / listUserProjects / listOrganizationProjects — project CRUD and discovery
• addProjectItem / deleteProjectItem / listProjectItems — manage items
• getProjectFields / updateProjectField — read and write custom fields

Views

• createProjectView / updateProjectView / deleteProjectView / listProjectViews

Priorities

• assessItemPriority — score one item's priority from its content and context
• batchUpdatePriorities — re-prioritize many items in one call

Dependencies & metrics

• manageItemDependencies / analyzeDependencies — model and analyze blocking relationships
• generateProjectMetrics — throughput/status summaries for a project

Example interaction

User: "What's blocking the v2 release?"

Agent calls listProjectItems on the release project → analyzeDependencies → reports the two items whose dependency chains are unresolved, with links.

Development

npm install
npm run build    # tsc → dist/
npm run watch    # rebuild on change

License

MIT