rriesco-mcp-github 0.1.0

MCP server for GitHub API operations - issues, PRs, CI, milestones

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

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scope: repo (full repository access)
4. 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.

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Links

• MCP Protocol Documentation
• PyGithub Documentation
• FastMCP Framework