# GitHub MCP Server

A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the GitHub API, built with Python and the official MCP SDK.

This server exposes **87 tools** across 25 categories, enabling AI agents like Claude to interact with GitHub repositories, issues, pull requests, discussions, projects, and more.

## Features

| Category | Tools | Description |
|----------|-------|-------------|
| **Repositories** | 7 | List, get, create, fork repos; list commits; get commit details; get file contents |
| **Issues** | 6 | List, get, create, update issues; manage comments |
| **Pull Requests** | 8 | List, get, create, update, merge PRs; view files/commits; update branch |
| **Search** | 4 | Search repositories, code, issues, and users |
| **Actions** | 4 | List workflows/runs, trigger workflows, cancel runs |
| **Releases** | 4 | List, get latest, create releases; get release by tag |
| **Tags** | 2 | List tags, get annotated tag details |
| **Git** | 2 | Get repository tree, push multiple files in a single commit |
| **Organizations** | 3 | List orgs, get details, list members |
| **Branches** | 3 | List, create, delete branches |
| **Branch Protection** | 3 | Get, update, delete branch protection rules |
| **Webhooks** | 3 | List, create, delete repository webhooks |
| **Files** | 2 | Create/update and delete files via the Contents API |
| **PR Reviews** | 2 | Create and list pull request reviews |
| **Review Comments** | 3 | List, create, reply to PR review comments |
| **Commit Statuses** | 4 | List/create commit statuses; list/get check runs |
| **Labels** | 3 | List, create, delete repository labels |
| **Gists** | 4 | List, get, create, update gists |
| **Stars** | 3 | List starred repos, star/unstar repositories |
| **Users** | 2 | Get authenticated user info, get any user's profile |
| **Notifications** | 3 | List notifications, mark as read |
| **Collaborators** | 3 | List, add, remove repository collaborators |
| **Discussions** | 4 | List, get discussions; view comments; list categories (GraphQL) |
| **Projects (Classic)** | 2 | List repository and organization projects |
| **Projects V2** | 3 | List, get projects; list project items (GraphQL) |

## Requirements

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- [GitHub Personal Access Token](https://github.com/settings/tokens)

## Installation

```bash
git clone https://github.com/software-engineer-mj/github-mcp.git
cd github-mcp
uv sync
```

## Configuration

```bash
cp .env.example .env
```

Edit the `.env` file:

```
GITHUB_TOKEN=ghp_your_token_here
```

### Token Permissions

Depending on which tools you use, your token needs these scopes:

| Scope | Required For |
|-------|-------------|
| `repo` | Repositories, issues, PRs, branches, webhooks, collaborators, files, tags, git |
| `read:org` | Organizations, org members, org projects |
| `gist` | Gists |
| `notifications` | Notifications |
| `user` | Authenticated user info, starring |
| `workflow` | GitHub Actions (trigger, cancel) |
| `read:discussion` | Discussions |
| `project` | Projects (Classic), Projects V2 |

## Usage

### stdio (default)

```bash
uv run python -m github_mcp
```

### Docker

```bash
docker build -t github-mcp .

docker run -e GITHUB_TOKEN=ghp_your_token github-mcp
```

## MCP Client Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "github": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/github-mcp", "python", "-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/github-mcp", "python", "-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

## Development

```bash
# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run mypy src/
```

## Tool Reference

### Repositories

| Tool | Description |
|------|-------------|
| `list_repositories` | List repositories for a user or organization |
| `get_repository` | Get detailed repository information |
| `create_repository` | Create a new repository |
| `fork_repository` | Fork a repository |
| `list_commits` | List commits with optional filters (author, date range) |
| `get_commit` | Get commit details including stats and changed files |
| `get_file_contents` | Get file contents or directory listing |

### Issues

| Tool | Description |
|------|-------------|
| `list_issues` | List issues with filters (state, labels, assignee) |
| `get_issue` | Get detailed issue information |
| `create_issue` | Create a new issue |
| `update_issue` | Update issue title, body, state, labels, assignees |
| `list_issue_comments` | List comments on an issue |
| `create_issue_comment` | Add a comment to an issue |

### Pull Requests

| Tool | Description |
|------|-------------|
| `list_pull_requests` | List PRs with filters (state, base, head) |
| `get_pull_request` | Get detailed PR info including mergeable status |
| `create_pull_request` | Create a new pull request |
| `update_pull_request` | Update PR title, body, state, base branch |
| `merge_pull_request` | Merge a PR (merge, squash, or rebase) |
| `list_pr_files` | List files changed in a PR |
| `list_pr_commits` | List commits in a PR |
| `update_pull_request_branch` | Update a PR branch with the latest base branch changes |

### Search

| Tool | Description |
|------|-------------|
| `search_repositories` | Search repos by name, language, stars, topics |
| `search_code` | Search code across repositories |
| `search_issues` | Search issues and PRs across GitHub |
| `search_users` | Search users by name, location, followers |

### Actions

| Tool | Description |
|------|-------------|
| `list_workflows` | List GitHub Actions workflows |
| `list_workflow_runs` | List workflow runs with status filters |
| `trigger_workflow` | Trigger a workflow dispatch event |
| `cancel_workflow_run` | Cancel a running workflow |

### Releases

| Tool | Description |
|------|-------------|
| `list_releases` | List releases in a repository |
| `get_latest_release` | Get the latest published release |
| `create_release` | Create a new release with tag |
| `get_release_by_tag` | Get a release by its tag name |

### Tags

| Tool | Description |
|------|-------------|
| `list_tags` | List tags in a repository |
| `get_tag` | Get an annotated tag object by SHA |

### Git

| Tool | Description |
|------|-------------|
| `get_repository_tree` | Get repository tree (directory listing) by SHA or branch |
| `push_files` | Push multiple files in a single commit via Git Data API |

### Organizations

| Tool | Description |
|------|-------------|
| `list_user_orgs` | List authenticated user's organizations |
| `get_organization` | Get organization details |
| `list_org_members` | List organization members |

### Branches

| Tool | Description |
|------|-------------|
| `list_branches` | List branches in a repository |
| `create_branch` | Create a new branch from an existing one |
| `delete_branch` | Delete a branch |

### Branch Protection

| Tool | Description |
|------|-------------|
| `get_branch_protection` | Get branch protection rules |
| `update_branch_protection` | Update branch protection settings |
| `delete_branch_protection` | Delete branch protection |

### Webhooks

| Tool | Description |
|------|-------------|
| `list_webhooks` | List repository webhooks |
| `create_webhook` | Create a webhook with event subscriptions |
| `delete_webhook` | Delete a webhook |

### Files

| Tool | Description |
|------|-------------|
| `create_or_update_file` | Create or update a file (requires SHA for updates) |
| `delete_file` | Delete a file from a repository |

### PR Reviews

| Tool | Description |
|------|-------------|
| `create_pr_review` | Submit a review (APPROVE, REQUEST_CHANGES, COMMENT) |
| `list_pr_reviews` | List reviews on a pull request |

### Review Comments

| Tool | Description |
|------|-------------|
| `list_review_comments` | List review comments on a pull request |
| `create_review_comment` | Create a review comment (line, multiline, or file) |
| `reply_to_review_comment` | Reply to an existing review comment |

### Commit Statuses

| Tool | Description |
|------|-------------|
| `list_commit_statuses` | List commit statuses for a ref |
| `create_commit_status` | Create a commit status (pending, success, failure, error) |
| `list_check_runs` | List check runs for a ref |
| `get_check_run` | Get details of a specific check run |

### Labels

| Tool | Description |
|------|-------------|
| `list_labels` | List repository labels |
| `create_label` | Create a label with color and description |
| `delete_label` | Delete a label |

### Gists

| Tool | Description |
|------|-------------|
| `list_gists` | List gists for a user or authenticated user |
| `get_gist` | Get gist details with file contents |
| `create_gist` | Create a new gist with multiple files |
| `update_gist` | Update gist description, files, or delete files |

### Stars

| Tool | Description |
|------|-------------|
| `list_starred_repos` | List starred repositories |
| `star_repository` | Star a repository |
| `unstar_repository` | Unstar a repository |

### Users

| Tool | Description |
|------|-------------|
| `get_authenticated_user` | Get current authenticated user's profile |
| `get_user` | Get any GitHub user's public profile |

### Notifications

| Tool | Description |
|------|-------------|
| `list_notifications` | List notifications with filters |
| `mark_notifications_read` | Mark all notifications as read |
| `mark_thread_read` | Mark a specific notification thread as read |

### Collaborators

| Tool | Description |
|------|-------------|
| `list_collaborators` | List repository collaborators |
| `add_collaborator` | Add a collaborator with permission level |
| `remove_collaborator` | Remove a collaborator |

### Discussions

| Tool | Description |
|------|-------------|
| `list_discussions` | List discussions in a repository |
| `get_discussion` | Get details of a specific discussion |
| `get_discussion_comments` | Get comments on a discussion with replies |
| `list_discussion_categories` | List discussion categories for a repository |

### Projects (Classic)

| Tool | Description |
|------|-------------|
| `list_repo_projects` | List repository projects (classic) |
| `list_org_projects` | List organization projects (classic) |

### Projects V2

| Tool | Description |
|------|-------------|
| `list_projects_v2` | List Projects V2 for an organization or user |
| `get_project_v2` | Get details of a specific Project V2 |
| `list_project_v2_items` | List items (issues, PRs, drafts) in a Project V2 |

## Project Structure

```
src/github_mcp/
├── __init__.py              # FastMCP server instance
├── __main__.py              # Entry point with auto-discovery
├── client.py                # Async GitHub API HTTP client (httpx)
├── exceptions.py            # Custom exception hierarchy
├── validators.py            # Input validation (enum, clamping)
└── tools/
    ├── __init__.py
    ├── actions.py            # GitHub Actions workflows
    ├── branch_protection.py  # Branch protection rules
    ├── branches.py           # Branch management
    ├── collaborators.py      # Collaborator management
    ├── commit_statuses.py    # Commit statuses and check runs
    ├── discussions.py        # Discussions (GraphQL)
    ├── files.py              # File create/update/delete
    ├── gists.py              # Gist operations
    ├── git.py                # Git Data API (tree, push files)
    ├── issues.py             # Issue operations
    ├── labels.py             # Label management
    ├── notifications.py      # Notification management
    ├── organizations.py      # Organization operations
    ├── projects.py           # Classic project boards
    ├── projects_v2.py        # Projects V2 (GraphQL)
    ├── pull_requests.py      # Pull request operations
    ├── releases.py           # Release management
    ├── repositories.py       # Repository operations
    ├── review_comments.py    # PR review comments
    ├── reviews.py            # PR review operations
    ├── search.py             # GitHub search
    ├── stars.py              # Star/unstar repositories
    ├── tags.py               # Tag operations
    ├── users.py              # User profile operations
    └── webhooks.py           # Webhook management
tests/
├── conftest.py              # Shared fixtures (mock GitHub client)
├── test_client.py           # HTTP client, retry, cache, error tests
├── test_exceptions.py       # Exception hierarchy tests
├── test_server.py           # Tool registration tests
├── test_validators.py       # Validator tests
└── tools/
    ├── conftest.py
    └── test_<domain>.py      # Tests matching each tool module
```

## License

MIT - see [LICENSE](LICENSE) for details.