GitHub Project MCP Server

A Model Context Protocol (MCP) server providing complementary tools for GitHub Projects V2 management. Install once, use with Claude Code, Claude Desktop, Cursor, Cline, and other MCP-compatible tools.

Quick Start

1. Install the Package

# Option A: Install globally with pip
pip install git+https://github.com/your-org/ghpro.git

# Option B: Clone and install locally
git clone <repository-url>
cd ghpro
pip install -e .

# Option C: Use uv (no install needed)
# Just configure the tool to run: uv run --directory /path/to/ghpro python -m github_project_mcp

2. Create a GitHub Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Create a token with these scopes:
   • repo - Full repository access
   • project - Project access
   • write:org - Organization access (for org projects)

3. Configure Your AI Tool

See Integration with AI Tools below.

---

Integration with AI Tools

Claude Code (CLI)

After installing the package, add to your MCP settings:

Project-level (.mcp.json in your repo):

{
  "mcpServers": {
    "github-project": {
      "command": "github-project-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Note: Unlike configuration that requires owner/repo as environment variables, this MCP follows the official GitHub MCP pattern. The AI tool infers owner and repo from your workspace context and passes them per-call. You only need to provide your GitHub token.

With default project number (optional):

{
  "mcpServers": {
    "github-project": {
      "command": "github-project-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token",
        "DEFAULT_PROJECT_NO": "1"
      }
    }
  }
}

Without installing (using uv):

{
  "mcpServers": {
    "github-project": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ghpro", "python", "-m", "github_project_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Claude Desktop

Add to config file:

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

{
  "mcpServers": {
    "github-project": {
      "command": "github-project-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Cursor / VS Code with Cline

Add to Cline MCP settings:

{
  "mcpServers": {
    "github-project": {
      "command": "github-project-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Continue.dev (VS Code)

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "github-project-mcp",
          "env": {
            "GITHUB_TOKEN": "ghp_your_token"
          }
        }
      }
    ]
  }
}

Zed Editor

Add to Zed settings:

{
  "context_servers": {
    "github-project": {
      "command": {
        "path": "github-project-mcp",
        "env": {
          "GITHUB_TOKEN": "ghp_your_token"
        }
      }
    }
  }
}

---

What This MCP Provides

Tool	Purpose
create_task	Create issue + add to project + set custom fields in one call
create_label / edit_label / delete_label	Label CRUD with auto-color theming
audit_issues	Find dangling, detached, or incomplete issues
calculate_estimates	Recursive estimate roll-up from children
bulk_operations	Batch create/update operations
create_project_field / update_project_field / delete_project_field	Custom field management
transfer_issue	Move issue between repositories
get_project_metrics	Project progress analytics

Use Official GitHub MCP For:

• Basic issue CRUD (issue_read, issue_write)
• Sub-issue linking (sub_issue_write)
• Issue search (search_issues)
• Project field listing (projects_list.list_project_fields)

---

Tool Examples

create_task

Create an issue and add it to a project with custom field values:

{
  "owner": "your-org",
  "repo": "your-repo",
  "title": "Implement authentication",
  "description": "Add OAuth2 support",
  "project_number": 1,
  "labels": ["backend", "security"],
  "issue_type": "Feature",
  "fields": {
    "Priority": {"option": "High"},
    "Estimate": 8,
    "Sprint": {"iteration": "Sprint 3"},
    "Due Date": {"date": "2026-02-15"}
  }
}

Note: The AI tool automatically fills owner and repo from your workspace context. You don't need to specify them manually. If project_number is omitted, it uses DEFAULT_PROJECT_NO env var or discovers the first linked project. The issue_type parameter sets the GitHub native issue type (only works for organization repositories with issue types enabled).

create_label

Create labels with auto-color theming:

{"name": "priority:high", "theme": "priority"}

Themes: github, priority, type, size, status

audit_issues

Find project health problems:

{
  "owner": "your-org",
  "repo": "your-repo",
  "project_number": 1,
  "find_dangling": true,
  "find_missing_fields": ["Estimate", "Priority"]
}

get_project_metrics

Get project analytics:

{
  "owner": "your-org",
  "repo": "your-repo",
  "project_number": 1
}

---

Configuration

Environment Variables

Variable	Required	Default	Description
GITHUB_TOKEN	Yes	-	Personal Access Token
DEFAULT_PROJECT_NO	No	-	Default project number (fallback if not specified per-call)
GITHUB_API_URL	No	https://api.github.com	For GitHub Enterprise
LOG_LEVEL	No	INFO	DEBUG, INFO, WARNING, ERROR

Per-Call Parameters

All tools accept owner and repo as required parameters. These are automatically filled by your AI tool from the workspace context:

Parameter	Description
owner	GitHub username or organization (inferred from workspace)
repo	Repository name (inferred from workspace)
project_number	Optional - uses DEFAULT_PROJECT_NO or auto-discovers first linked project

---

Features

Rate Limiting & Automatic Retry

The client automatically:

• Tracks GitHub API rate limits from response headers
• Waits when approaching limit exhaustion
• Retries with exponential backoff on:
  • Rate limit errors (403)
  • Server errors (5xx)
  • Network errors
  • Transient errors ("timeout", "try again")

Pagination

All queries use cursor-based pagination for projects with >100 items.

Generic Field Handling

Works with ANY project field configuration:

fields={
    "Priority": {"option": "High"},      # SINGLE_SELECT
    "Estimate": 5,                        # NUMBER
    "Due Date": {"date": "2026-02-15"},  # DATE
    "Sprint": {"iteration": "Sprint 3"}, # ITERATION
    "Notes": "Some text",                 # TEXT
}

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/

# Linting
ruff check src/

---

Project Structure

ghpro/
├── pyproject.toml
├── src/github_project_mcp/
│   ├── __init__.py
│   ├── __main__.py           # python -m entry point
│   ├── server.py             # MCP server
│   ├── config.py             # Pydantic settings
│   ├── client/
│   │   ├── github.py         # GraphQL client with retry
│   │   └── queries.py        # GraphQL query strings
│   ├── tools/                # 12 tool implementations
│   ├── models/               # Pydantic models
│   └── utils/                # Helpers
└── tests/

---

Troubleshooting

"Command not found: github-project-mcp"

• Ensure package is installed: pip install -e .
• Check it's in PATH: which github-project-mcp
• Or use full path: python -m github_project_mcp

"Project not found"

• Verify GITHUB_PROJECT_NUMBER or project_number parameter
• Check GITHUB_OWNER_TYPE is correct (user or org)

"Field not found"

• Use exact field names (case-sensitive)
• Use official MCP's list_project_fields to discover field names

"Rate limit exceeded"

• The client auto-retries with backoff
• Check error details for retry_after value

---

License

MIT License - see LICENSE file

Contributing

Contributions welcome! Please open an issue or pull request.