GitHub Projects MCP Server: GraphQL Items, Fields, Milestones

Overview

The GitHub Projects MCP Server provides a lightweight, self-hosted GraphQL API that surfaces GitHub Projects data—items, custom fields, and milestones—through the Model Context Protocol (MCP) pattern. It is intended to make project automation and integrations easier by exposing a consistent GraphQL surface for reading and updating project state across repositories and organizations.

By running the server you get a single GraphQL endpoint you can query from scripts, CI, or external tools to list project items, read and write custom field values, and create or sync milestones. This is useful for teams that need programmatic control over project boards, cross-repo planning, or automated reporting without having to call multiple GitHub REST endpoints or handle different UI-only workflows.

Features

• Full GraphQL access to project items, custom fields, and milestones
• Read and write operations for item field values and milestone synchronization
• Single endpoint for multi-repo / multi-project automation
• Local development server with GraphQL playground for exploring the schema
• Docker-friendly for simple deployment
• Authentication via GitHub token / app (configurable through env vars)
• Example queries and mutation templates to get started quickly

Installation / Configuration

Prerequisites:

• Node.js (16+ recommended)
• A GitHub token with appropriate scopes (repo, project, workflow) or a GitHub App

Clone and install:

git clone https://github.com/redducklabs/github-projects-mcp.git
cd github-projects-mcp
npm install
# or
pnpm install

Create an environment file (.env) with at least a GitHub token:

# .env
GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
PORT=4000
# Optional GitHub App configuration (if you run as an app)
# GITHUB_APP_ID=12345
# GITHUB_PRIVATE_KEY_PATH=./private-key.pem

Common environment variables

Run locally:

# development with hot reload (if script provided)
npm run dev

# production
npm run build
npm start

Run with Docker:

docker build -t github-projects-mcp .
docker run -e GITHUB_TOKEN=$GITHUB_TOKEN -p 4000:4000 github-projects-mcp

See the repository for additional configuration options and deployment examples: https://github.com/redducklabs/github-projects-mcp

Available Resources

• GraphQL endpoint: http://localhost:4000/graphql
• GraphQL Playground: http://localhost:4000/playground (if enabled)
• Schema and type definitions are bundled in the repo; open them locally to discover exact queries/mutations
• Example queries and cURL templates in the repo’s examples directory
• Dockerfile and npm scripts for quick deployment

Example GraphQL operations

Below are representative examples to illustrate how the API is typically used. Check the server schema for exact type names and arguments.

List items and their fields:

query ListProjectItems($owner: String!, $repo: String!, $projectNumber: Int!) {
  projectItems(owner: $owner, repo: $repo, projectNumber: $projectNumber) {
    id
    title
    number
    fields {
      id
      name
      value
    }
  }
}

Update an item’s field value:

mutation UpdateField($itemId: ID!, $fieldId: ID!, $value: String!) {
  updateItemField(input: { itemId: $itemId, fieldId: $fieldId, value: $value }) {
    success
    item {
      id
      fields {
        id
        name
        value
      }
    }
  }
}

Create or sync a milestone:

mutation CreateMilestone($repoId: ID!, $title: String!) {
  createMilestone(input: { repositoryId: $repoId, title: $title }) {
    milestone {
      id
      title
      dueOn
    }
  }
}

Use Cases

• Automating triage: run a CI job that queries unassigned project items and assigns them to queues or people based on labels or custom field values.
• Milestone synchronization: create or update repository milestones from a centralized project field, keeping roadmap artifacts consistent across repos.
• Cross-repo planning: pull items from multiple repositories into a single view and update priorities or statuses in bulk from your automation scripts.
• Reporting and dashboards: periodically query items and fields to generate CSV/JSON exports or feed data into dashboards for weekly standups.
• Integrations: use the MCP server as a standardized backend for internal tooling (Slack bots, webhooks consumers, or chatops) that need to read/write project state.

Tips for developers

• Start by exploring the GraphQL Playground to learn the exact schema and available queries/mutations.
• Ensure your token has the required GitHub scopes; missing permissions are a common source of errors.
• For automation, prefer non-interactive tokens (machine users or GitHub Actions secrets) and store them securely in your CI/CD system.
• Use pagination for queries that return many items; the schema typically supports cursors/limits.