GitHub MCP Server

A comprehensive Model Context Protocol (MCP) 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 (recommended) or pip
• GitHub Personal Access Token

Installation

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

Configuration

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)

uv run python -m github_mcp

Docker

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

{
  "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:

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

Development

# 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 for details.