GitHub MCP Server

Python MCP (Model Context Protocol) server for GitHub operations, providing native tool integration with Claude Code and other MCP clients.

Features

16 GitHub Tools: Issues, PRs, CI status, milestones, and batch operations
Native MCP Integration: Works seamlessly with Claude Code
Structured Responses: Type-safe, well-formatted tool outputs
Batch Operations: Parallel execution for bulk operations
Environment-Based Config: Configure default repository via environment variables

Installation

From PyPI

pip install github-mcp-server
# or with uv
uvx github-mcp-server

From Source

git clone https://github.com/rriesco/github-mcp-server.git
cd github-mcp-server
uv sync

Configuration

Environment Variables

Variable	Required	Description
`GITHUB_TOKEN`	Yes	GitHub Personal Access Token with `repo` scope
`GITHUB_OWNER`	No	Default repository owner for all operations
`GITHUB_REPO`	No	Default repository name for all operations

Claude Code Configuration

Add to your MCP configuration (~/.config/claude-code/mcp-config.json):

{
  "mcpServers": {
    "github-manager": {
      "type": "stdio",
      "command": "uvx",
      "args": ["github-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_OWNER": "your-username",
        "GITHUB_REPO": "your-repo"
      }
    }
  }
}

Getting a GitHub Token

Go to https://github.com/settings/tokens
Click "Generate new token (classic)"
Select scope: repo (full repository access)
Copy the generated token

Available Tools

Issue Operations

Tool	Description
`create_issues`	Create one or more issues (parallel execution for multiple)
`get_issue`	Get full issue details including body
`list_issues`	Query issues with filtering (state, labels, milestone, assignee)
`close_issue`	Close an issue with optional comment

Pull Request Operations

Tool	Description
`create_pr_with_content`	Create PR with structured content (problem, solution, changes)
`get_pull_request`	Get PR details including mergeable status
`update_pr`	Update PR title, body, base branch, or state
`merge_pr`	Merge PR with method selection (squash/merge/rebase)

CI/CD Operations

Tool	Description
`check_ci_status`	Check workflow run status for a branch
`get_ci_logs`	Get CI logs for debugging failed jobs

Batch Operations

Tool	Description
`batch_update_issues`	Update multiple issues in parallel
`batch_add_labels`	Add labels to multiple issues
`batch_link_to_project`	Link issues to GitHub Project (v2)

Milestone Operations

Tool	Description
`create_milestone`	Create a milestone with optional due date
`list_milestones`	List milestones with filtering

Usage Examples

Create an Issue

result = create_issues(
    issues=[{
        "title": "Implement feature X",
        "body": "## Description\n\nDetails here...",
        "labels": ["enhancement"],
        "milestone": 1
    }],
    owner="your-username",
    repo="your-repo"
)

Check CI Status

result = check_ci_status(
    branch="feature-branch",
    owner="your-username",
    repo="your-repo"
)

Create a PR

result = create_pr_with_content(
    title="feat: add new feature",
    problem="Current behavior lacks X functionality",
    solution="Implement X using approach Y",
    key_changes="- Added X component\n- Updated Y module",
    issue=42,  # Optional: links to issue #42
    owner="your-username",
    repo="your-repo"
)

Development

Prerequisites

Python >= 3.10
uv (recommended) or pip
GitHub Personal Access Token

Setup

git clone https://github.com/rriesco/github-mcp-server.git
cd github-mcp-server
uv sync

Running Tests

# Unit tests only (fast)
uv run pytest -m "not integration" -v

# Integration tests (requires GITHUB_TOKEN, TEST_OWNER, TEST_REPO)
uv run pytest -m integration -v

# All tests with coverage
uv run pytest --cov=src --cov-report=term-missing

Type Checking

uv run mypy src/github_mcp_server --strict

Architecture

Claude Code / MCP Client
      |
      | MCP Protocol (stdio)
      v
┌─────────────────────────────┐
│  Python FastMCP Server      │
│  - Tool Registry            │
│  - PyGithub Client          │
│  - Error Handling           │
│  - Type Validation          │
└─────────────┬───────────────┘
              |
              | PyGithub REST API
              v
        GitHub API

Project Structure

github-mcp-server/
├── src/github_mcp_server/
│   ├── server.py              # Server entry point
│   ├── tools/
│   │   ├── issues.py          # Issue operations
│   │   ├── pulls.py           # PR operations
│   │   ├── ci.py              # CI operations
│   │   ├── milestones.py      # Milestone operations
│   │   └── batch_operations.py # Batch operations
│   ├── utils/
│   │   ├── github_client.py   # Singleton PyGithub client
│   │   ├── errors.py          # Structured error handling
│   │   └── types.py           # Type definitions
│   └── config/
│       └── defaults.py        # Environment-based defaults
└── tests/
    ├── test_*.py              # Unit tests
    └── integration/           # Integration tests

License

MIT License - see LICENSE for details.

GitHub MCP Server

GitHub MCP Server

Features

Installation

From PyPI

From Source

Configuration

Environment Variables

Claude Code Configuration

Getting a GitHub Token

Available Tools

Issue Operations

Pull Request Operations

CI/CD Operations

Batch Operations

Milestone Operations

Usage Examples

Create an Issue

Check CI Status

Create a PR

Development

Prerequisites

Setup

Running Tests

Type Checking

Architecture

Project Structure

License

Links

Latest Blog Posts

MCP directory API