GitHub 项目管理 MCP 服务

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

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

Per-Call Parameters

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

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.