Model Context Protocol (MCP) server that provides tools for working with GitHub Projects via GraphQL, enabling complete project management including items, fields, and workflows.

Installation

From Source

git clone https://github.com/redducklabs/github-projects-mcp.git
cd github-projects-mcp
pip install -e .

Using pip

pip install github-projects-mcp

Using uv

uv add github-projects-mcp

DXT Package

Download the .dxt file from releases and install in Claude Desktop

Configuration

Claude Code (PyPI)

claude mcp add github-projects github-projects-mcp -e GITHUB_TOKEN=your_token_here

Claude Code (Source)

claude mcp add github-projects ./venv/Scripts/python github_projects_mcp/server.py -e GITHUB_TOKEN=your_token_here -e PYTHONPATH=/full/path/to/github-projects-mcp

Claude Desktop Manual

{
  "mcpServers": {
    "github-projects": {
      "command": "github-projects-mcp",
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

VS Code MCP

{
  "inputs": [
    {
      "type": "promptString",
      "id": "github-token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "github-projects": {
      "type": "stdio",
      "command": "github-projects-mcp",
      "env": {
        "GITHUB_TOKEN": "${input:github-token}"
      }
    }
  }
}

Available Tools

Tool	Description
list_accessible_projects	Get a list of all projects accessible to the authenticated user
get_organization_projects	Get organization projects
get_user_projects	Get user projects
get_project	Get a specific project by ID
create_project	Create a new project
update_project	Update project details
delete_project	Delete a project
get_project_items	Get project items (full data)
get_project_items_advanced	Get items with custom GraphQL field selection for efficiency
add_item_to_project	Add an item to a project
update_item_field_value	Update item field values
remove_item_from_project	Remove an item from a project
archive_item	Archive a project item
get_project_fields	Get project fields
search_project_items	Search items by content/fields

Features

• Complete GitHub Projects API coverage with all major operations
• Multiple transport modes (stdio, SSE, HTTP streaming)
• Robust error handling with GitHub API error display
• Configurable retries on rate limit
• Type safety with Pydantic models
• Configuration via environment variables
• Project discovery and management
• Project item management (add, update, delete, archive)
• Working with project fields
• Search and filtering capabilities

Environment Variables

Required

• GITHUB_TOKEN - GitHub Personal Access Token with project and read:project scopes

Optional

• API_MAX_RETRIES - Maximum number of retries on rate limit (default: 3)
• API_RETRY_DELAY - Delay in seconds between retries (default: 60)
• MCP_TRANSPORT - Transport mode - stdio, sse, or http (default: stdio)
• MCP_HOST - Host for SSE/HTTP modes (default: localhost)
• MCP_PORT - Port for SSE/HTTP modes (default: 8000)
• LOG_LEVEL - Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)

Usage Examples

@github-projects show me all projects for my organization 'mycompany'

@github-projects add issue #123 from repo mycompany/myproject to project PVT_kwDOABCDEF

@github-projects update the status field for item PVTI_lADOGHIJKL to 'In Progress'

@github-projects create a new project called 'Q1 Planning' for organization mycompany

@github-projects help me manage my project

Notes

Requires a GitHub Personal Access Token with 'project' and 'read:project' scopes. For organization projects, use a Fine-grained Personal Access Token with access to organization resources. Supports stdio (default), SSE, and HTTP transport modes. Compatible with Claude Code, VS Code MCP, and Claude Desktop.