GitHub Projects V2 MCP

Overview

GitHub Projects V2 MCP is an official GitHub-backed Model Context Protocol server designed specifically for interacting with GitHub Projects (the V2 version). Released in July 2026 with over 1,500 GitHub stars, this server enables AI agents to manage project boards, issues, pull requests, and milestones through natural language commands.

Migrated to the official GitHub organization and reaching v2.1, this MCP server provides enterprise-grade features including webhook callbacks, natural language filtering, and comprehensive project board management. It's essential for teams using GitHub Projects to automate project management workflows through AI agents.

Features

• Project Board Management: Create, update, and query GitHub Projects (V2)
• Issue and PR Operations: Create, update, and query issues and pull requests
• Milestone Management: Manage project milestones and tracking
• Natural Language Filtering: Query items using natural language (e.g., "find all unassigned high-priority bugs")
• Webhook Integration: Receive real-time notifications when project state changes
• Kanban Board Access: Read and modify project board columns and card states
• Field Customization: Work with custom project fields (dates, labels, numbers)
• GraphQL API Access: Direct access to GitHub's GraphQL Projects API

Installation

# Install via npm
npm install -g @github/mcp-projects-v2

# Or via npx (no installation)
npx @github/mcp-projects-v2

Configuration

{
  "mcpServers": {
    "github-projects-v2": {
      "command": "npx",
      "args": ["@github/mcp-projects-v2"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
        "GITHUB_OWNER": "your-org",
        "GITHUB_PROJECT_NUMBER": "1"
      }
    }
  }
}

Environment Variables:

Variable	Description	Required
GITHUB_TOKEN	GitHub Personal Access Token	Yes
GITHUB_OWNER	GitHub owner (user or organization)	No
GITHUB_PROJECT_NUMBER	Project number (if fixed)	No
MCP_LOG_LEVEL	Logging verbosity	No

Available Tools

Tool	Description
create_project	Create a new GitHub Project (V2)
get_project	Get project details and structure
list_projects	List all projects for an owner
create_issue	Create an issue in the project
update_issue	Update issue fields and status
list_issues	List issues with optional filters
create_pr	Create a pull request
list_prs	List pull requests with filters
add_to_project	Add item (issue/PR) to project board
update_project_item	Update item position or fields
natural_language_query	Query items using natural language
create_milestone	Create a project milestone
list_milestones	List all milestones
set_webhook	Configure webhook for project changes

Usage Examples

Example 1: Create a New Project

response = mcp_client.call_tool("github-projects-v2", "create_project", {
    "owner": "your-org",
    "title": "AI Agent Development Q3",
    "description": "Q3 roadmap for AI agent features",
    "template": "kanban"  # "kanban", "table", "timeline"
})

Example 2: Natural Language Query

response = mcp_client.call_tool("github-projects-v2", "natural_language_query", {
    "project_number": "1",
    "query": "Find all unassigned high-priority bugs that are blocked"
})
# Returns filtered list of matching items

Example 3: Create Issue and Add to Project

# Create issue
issue = mcp_client.call_tool("github-projects-v2", "create_issue", {
    "owner": "your-org",
    "repo": "your-repo",
    "title": "Fix memory leak in agent orchestrator",
    "body": "Agent orchestrator leaks memory after 100 requests",
    "labels": ["bug", "priority-high"],
    "assignees": ["@username"]
})

# Add to project
mcp_client.call_tool("github-projects-v2", "add_to_project", {
    "project_number": "1",
    "item_id": issue["id"],
    "status": "Todo"
})

Example 4: Webhook Configuration

response = mcp_client.call_tool("github-projects-v2", "set_webhook", {
    "project_number": "1",
    "webhook_url": "https://your-server.com/webhooks/github",
    "events": ["project_item_added", "project_item_updated", "project_item_status_changed"]
})

Example 5: Update Issue Status

response = mcp_client.call_tool("github-projects-v2", "update_project_item", {
    "project_number": "1",
    "item_id": "issue-123",
    "status": "In Progress",
    "fields": {
        "Priority": "High",
        "Sprint": "Sprint 5"
    }
})

Webhook Integration

Webhooks enable real-time project tracking:

# Webhook payload example
{
  "action": "project_item_updated",
  "project": {
    "number": 1,
    "title": "AI Agent Development Q3"
  },
  "item": {
    "id": "issue-123",
    "type": "Issue",
    "status": "In Progress",
    "fields": {
      "Priority": "High"
    }
  },
  "changed_fields": ["status", "Priority"]
}

Advanced Features

Custom Fields Management

# Get custom fields
response = mcp_client.call_tool("github-projects-v2", "get_custom_fields", {
    "project_number": "1"
})

# Update custom field
response = mcp_client.call_tool("github-projects-v2", "update_project_item", {
    "project_number": "1",
    "item_id": "issue-123",
    "fields": {
        "Due Date": "2026-08-15",
        "Story Points": 8,
        "Component": "Backend"
    }
})

Milestone Tracking

# Create milestone
mcp_client.call_tool("github-projects-v2", "create_milestone", {
    "project_number": "1",
    "title": "Agent v2.0 Release",
    "due_on": "2026-09-30"
})

# List milestones
response = mcp_client.call_tool("github-projects-v2", "list_milestones", {
    "project_number": "1"
})

Batch Operations

# Batch update multiple items
mcp_client.call_tool("github-projects-v2", "batch_update", {
    "project_number": "1",
    "updates": [
        {"item_id": "issue-1", "status": "Done"},
        {"item_id": "issue-2", "status": "In Progress"},
        {"item_id": "issue-3", "status": "Todo"}
    ]
})

Pros

• ✅ Official GitHub Support: Maintained by GitHub organization
• ✅ V2 Projects Native: Built for the new GitHub Projects API
• ✅ Natural Language Queries: Intuitive filtering without complex filters
• ✅ Webhook Integration: Real-time project change notifications
• ✅ Complete CRUD: Full create/read/update/delete for issues and PRs
• ✅ Custom Fields: Support for project-specific fields

Cons

• ✅ GitHub Token Required: Requires Personal Access Token setup
• ✅ API Rate Limits: Subject to GitHub API rate limiting
• ✅ V2 Only: Doesn't support legacy Projects (V1)
• ✅ New Server: Limited production track record

When to Use

• Project Management Automation: Automate issue and PR workflows
• Status Tracking: Keep project boards updated automatically
• Reporting: Generate project status reports through agents
• Webhook Integration: Build real-time project dashboards
• Team Collaboration: Coordinate distributed teams through AI agents
• Release Management: Track milestones and release progress

Resources

• GitHub Repository
• GitHub Projects API
• GraphQL Projects API