GitHub MCP Server
Enables low-level Git operations through the GitHub API, including retrieving repository trees and pushing multiple files in a single commit.
Allows for comprehensive interaction with GitHub's API to manage repositories, issues, pull requests, organizations, gists, and user profiles.
Provides tools to manage GitHub Actions, enabling users to list workflows, monitor workflow runs, trigger dispatch events, and cancel active runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GitHub MCP Server list the most recent pull requests for the github-mcp repository"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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) |
Related MCP server: GitHub MCP Server
Requirements
Python >= 3.10
uv (recommended) or pip
Installation
git clone https://github.com/software-engineer-mj/github-mcp.git
cd github-mcp
uv syncConfiguration
cp .env.example .envEdit the .env file:
GITHUB_TOKEN=ghp_your_token_hereToken Permissions
Depending on which tools you use, your token needs these scopes:
Scope | Required For |
| Repositories, issues, PRs, branches, webhooks, collaborators, files, tags, git |
| Organizations, org members, org projects |
| Gists |
| Notifications |
| Authenticated user info, starring |
| GitHub Actions (trigger, cancel) |
| Discussions |
| Projects (Classic), Projects V2 |
Usage
stdio (default)
uv run python -m github_mcpDocker
docker build -t github-mcp .
docker run -e GITHUB_TOKEN=ghp_your_token github-mcpMCP 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 for a user or organization |
| Get detailed repository information |
| Create a new repository |
| Fork a repository |
| List commits with optional filters (author, date range) |
| Get commit details including stats and changed files |
| Get file contents or directory listing |
Issues
Tool | Description |
| List issues with filters (state, labels, assignee) |
| Get detailed issue information |
| Create a new issue |
| Update issue title, body, state, labels, assignees |
| List comments on an issue |
| Add a comment to an issue |
Pull Requests
Tool | Description |
| List PRs with filters (state, base, head) |
| Get detailed PR info including mergeable status |
| Create a new pull request |
| Update PR title, body, state, base branch |
| Merge a PR (merge, squash, or rebase) |
| List files changed in a PR |
| List commits in a PR |
| Update a PR branch with the latest base branch changes |
Search
Tool | Description |
| Search repos by name, language, stars, topics |
| Search code across repositories |
| Search issues and PRs across GitHub |
| Search users by name, location, followers |
Actions
Tool | Description |
| List GitHub Actions workflows |
| List workflow runs with status filters |
| Trigger a workflow dispatch event |
| Cancel a running workflow |
Releases
Tool | Description |
| List releases in a repository |
| Get the latest published release |
| Create a new release with tag |
| Get a release by its tag name |
Tags
Tool | Description |
| List tags in a repository |
| Get an annotated tag object by SHA |
Git
Tool | Description |
| Get repository tree (directory listing) by SHA or branch |
| Push multiple files in a single commit via Git Data API |
Organizations
Tool | Description |
| List authenticated user's organizations |
| Get organization details |
| List organization members |
Branches
Tool | Description |
| List branches in a repository |
| Create a new branch from an existing one |
| Delete a branch |
Branch Protection
Tool | Description |
| Get branch protection rules |
| Update branch protection settings |
| Delete branch protection |
Webhooks
Tool | Description |
| List repository webhooks |
| Create a webhook with event subscriptions |
| Delete a webhook |
Files
Tool | Description |
| Create or update a file (requires SHA for updates) |
| Delete a file from a repository |
PR Reviews
Tool | Description |
| Submit a review (APPROVE, REQUEST_CHANGES, COMMENT) |
| List reviews on a pull request |
Review Comments
Tool | Description |
| List review comments on a pull request |
| Create a review comment (line, multiline, or file) |
| Reply to an existing review comment |
Commit Statuses
Tool | Description |
| List commit statuses for a ref |
| Create a commit status (pending, success, failure, error) |
| List check runs for a ref |
| Get details of a specific check run |
Labels
Tool | Description |
| List repository labels |
| Create a label with color and description |
| Delete a label |
Gists
Tool | Description |
| List gists for a user or authenticated user |
| Get gist details with file contents |
| Create a new gist with multiple files |
| Update gist description, files, or delete files |
Stars
Tool | Description |
| List starred repositories |
| Star a repository |
| Unstar a repository |
Users
Tool | Description |
| Get current authenticated user's profile |
| Get any GitHub user's public profile |
Notifications
Tool | Description |
| List notifications with filters |
| Mark all notifications as read |
| Mark a specific notification thread as read |
Collaborators
Tool | Description |
| List repository collaborators |
| Add a collaborator with permission level |
| Remove a collaborator |
Discussions
Tool | Description |
| List discussions in a repository |
| Get details of a specific discussion |
| Get comments on a discussion with replies |
| List discussion categories for a repository |
Projects (Classic)
Tool | Description |
| List repository projects (classic) |
| List organization projects (classic) |
Projects V2
Tool | Description |
| List Projects V2 for an organization or user |
| Get details of a specific Project V2 |
| 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 moduleLicense
MIT - see LICENSE for details.
Available Tools
87 toolsadd_collaboratorB
Add a collaborator to a repository.
Inputs: owner (required), repo (required), username (required), permission. Returns: result
cancel_workflow_runC
Cancel a workflow run.
Inputs: owner (required), repo (required), run_id (required). Returns: result
create_branchB
Create a new branch in a repository.
Inputs: owner (required), repo (required), branch_name (required), from_branch. Returns: result
create_commit_statusB
Create a commit status for a specific SHA.
Inputs: owner (required), repo (required), sha (required), state (required), +3 more. Returns: result
create_gistB
Create a new gist.
Inputs: files (required), description, public. Returns: result
create_issueB
Create a new issue in a repository.
Inputs: owner (required), repo (required), title (required), body, +2 more. Returns: result
create_issue_commentB
Add a comment to an issue.
Inputs: owner (required), repo (required), issue_number (required), body (required). Returns: result
create_labelC
Create a label in a repository.
Inputs: owner (required), repo (required), name (required), color (required), +1 more. Returns: result
create_or_update_fileA
Create or update a file in a repository. To update, you must provide the current file's SHA.
Inputs: owner (required), repo (required), path (required), content (required), +3 more. Returns: result
create_pr_reviewB
Create a review on a pull request.
Inputs: owner (required), repo (required), pull_number (required), event (required), +1 more. Returns: result
create_pull_requestC
Create a new pull request.
Inputs: owner (required), repo (required), title (required), head (required), +3 more. Returns: result
create_releaseC
Create a new release.
Inputs: owner (required), repo (required), tag_name (required), name, +5 more. Returns: result
create_repositoryB
Create a new repository for the authenticated user.
Inputs: name (required), description, private, auto_init. Returns: result
create_review_commentB
Create a review comment on a specific line of a pull request diff.
Inputs: owner (required), repo (required), pull_number (required), body (required), +7 more. Returns: result
create_webhookB
Create a webhook for a repository.
Inputs: owner (required), repo (required), url (required), events, +3 more. Returns: result
delete_branchC
Delete a branch from a repository.
Inputs: owner (required), repo (required), branch (required). Returns: result
delete_branch_protectionC
Delete branch protection rules for a branch.
Inputs: owner (required), repo (required), branch (required). Returns: result
delete_fileC
Delete a file from a repository.
Inputs: owner (required), repo (required), path (required), message (required), +2 more. Returns: result
delete_labelB
Delete a label from a repository.
Inputs: owner (required), repo (required), name (required). Returns: result
delete_webhookB
Delete a webhook from a repository.
Inputs: owner (required), repo (required), hook_id (required). Returns: result
fork_repositoryC
Fork a repository.
Inputs: owner (required), repo (required), organization. Returns: result
get_authenticated_userB
Get information about the currently authenticated user.
Inputs: no named parameters. Returns: result
get_branch_protectionB
Get branch protection rules for a branch.
Inputs: owner (required), repo (required), branch (required). Returns: result
get_check_runB
Get a single check run by ID.
Inputs: owner (required), repo (required), check_run_id (required). Returns: result
get_commitB
Get details of a specific commit including stats and changed files.
Inputs: owner (required), repo (required), ref (required). Returns: result
get_discussionB
Get details of a specific discussion.
Inputs: owner (required), repo (required), number (required). Returns: result
get_discussion_commentsC
Get comments on a discussion.
Inputs: owner (required), repo (required), number (required), first. Returns: result
get_file_contentsB
Get the contents of a file or directory listing in a repository. Returns JSON with a 'type' field ('file' or 'directory') for consistent parsing.
Inputs: owner (required), repo (required), path (required), ref. Returns: result
get_gistB
Get a specific gist with its file contents.
Inputs: gist_id (required). Returns: result
get_issueB
Get detailed information about a specific issue.
Inputs: owner (required), repo (required), issue_number (required). Returns: result
get_latest_releaseB
Get the latest published release of a repository.
Inputs: owner (required), repo (required). Returns: result
get_organizationC
Get detailed information about an organization.
Inputs: org (required). Returns: result
get_project_v2C
Get details of a specific Project V2.
Inputs: owner (required), project_number (required), owner_type. Returns: result
get_pull_requestC
Get detailed information about a pull request.
Inputs: owner (required), repo (required), pull_number (required). Returns: result
get_release_by_tagB
Get a release by its tag name.
Inputs: owner (required), repo (required), tag (required). Returns: result
get_repositoryB
Get detailed information about a repository.
Inputs: owner (required), repo (required). Returns: result
get_repository_treeA
Get a repository tree (directory listing) by SHA or branch name. Set recursive=True to get the full nested file tree.
Inputs: owner (required), repo (required), tree_sha (required), recursive. Returns: result
get_tagA
Get an annotated tag object by its SHA. Only works for annotated tags, not lightweight tags.
Inputs: owner (required), repo (required), tag_sha (required). Returns: result
get_userB
Get public information about a GitHub user.
Inputs: username (required). Returns: result
list_branchesB
List branches in a repository.
Inputs: owner (required), repo (required), protected, per_page, +1 more. Returns: result
list_check_runsB
List check runs for a reference (branch, tag, or SHA).
Inputs: owner (required), repo (required), ref (required), check_name, +3 more. Returns: result
list_collaboratorsB
List collaborators of a repository.
Inputs: owner (required), repo (required), affiliation, per_page, +1 more. Returns: result
list_commitsB
List commits in a repository.
Inputs: owner (required), repo (required), sha, author, +4 more. Returns: result
list_commit_statusesB
List commit statuses for a reference (branch, tag, or SHA).
Inputs: owner (required), repo (required), ref (required), per_page, +1 more. Returns: result
list_discussion_categoriesB
List discussion categories for a repository.
Inputs: owner (required), repo (required). Returns: result
list_discussionsC
List discussions in a repository.
Inputs: owner (required), repo (required), first, category_id. Returns: result
list_gistsB
List gists for a user or the authenticated user.
Inputs: username, per_page, page. Returns: result
list_issue_commentsB
List comments on an issue.
Inputs: owner (required), repo (required), issue_number (required), per_page, +1 more. Returns: result
list_issuesC
List issues in a repository.
Inputs: owner (required), repo (required), state, labels, +5 more. Returns: result
list_labelsC
List labels in a repository.
Inputs: owner (required), repo (required), per_page, page. Returns: result
list_notificationsB
List notifications for the authenticated user.
Inputs: all, participating, since, per_page, +1 more. Returns: result
list_org_membersB
List members of an organization.
Inputs: org (required), role, per_page, page. Returns: result
list_org_projectsB
List projects in an organization (classic projects).
Inputs: org (required), state, per_page, page. Returns: result
list_pr_commitsB
List commits in a pull request.
Inputs: owner (required), repo (required), pull_number (required), per_page, +1 more. Returns: result
list_pr_filesB
List files changed in a pull request.
Inputs: owner (required), repo (required), pull_number (required), per_page, +1 more. Returns: result
list_projects_v2C
List Projects V2 for an organization or user.
Inputs: owner (required), owner_type, first. Returns: result
list_project_v2_itemsB
List items in a Project V2 (issues, PRs, and draft items).
Inputs: owner (required), project_number (required), owner_type, first. Returns: result
list_pr_reviewsB
List reviews on a pull request.
Inputs: owner (required), repo (required), pull_number (required), per_page, +1 more. Returns: result
list_pull_requestsB
List pull requests in a repository.
Inputs: owner (required), repo (required), state, sort, +5 more. Returns: result
list_releasesB
List releases in a repository.
Inputs: owner (required), repo (required), per_page, page. Returns: result
list_repo_projectsB
List projects in a repository (classic projects).
Inputs: owner (required), repo (required), state, per_page, +1 more. Returns: result
list_repositoriesB
List repositories for a user or organization.
Inputs: owner (required), type, sort, per_page, +1 more. Returns: result
list_review_commentsB
List review comments on a pull request.
Inputs: owner (required), repo (required), pull_number (required), sort, +3 more. Returns: result
list_starred_reposB
List repositories starred by a user or the authenticated user.
Inputs: username, sort, direction, per_page, +1 more. Returns: result
list_tagsB
List tags in a repository.
Inputs: owner (required), repo (required), per_page, page. Returns: result
list_user_orgsB
List organizations for the authenticated user.
Inputs: per_page, page. Returns: result
list_webhooksB
List webhooks for a repository.
Inputs: owner (required), repo (required), per_page, page. Returns: result
list_workflow_runsB
List workflow runs for a repository or specific workflow.
Inputs: owner (required), repo (required), workflow_id, branch, +3 more. Returns: result
list_workflowsB
List GitHub Actions workflows in a repository.
Inputs: owner (required), repo (required), per_page, page. Returns: result
mark_notifications_readB
Mark all notifications as read.
Inputs: last_read_at. Returns: result
mark_thread_readB
Mark a specific notification thread as read.
Inputs: thread_id (required). Returns: result
merge_pull_requestC
Merge a pull request.
Inputs: owner (required), repo (required), pull_number (required), commit_title, +2 more. Returns: result
push_filesA
Push multiple files to a branch in a single commit using the Git Data API. This creates blobs, a tree, a commit, and updates the branch ref atomically.
Inputs: owner (required), repo (required), branch (required), files (required), +1 more. Returns: result
remove_collaboratorB
Remove a collaborator from a repository.
Inputs: owner (required), repo (required), username (required). Returns: result
reply_to_review_commentB
Reply to an existing review comment on a pull request.
Inputs: owner (required), repo (required), pull_number (required), comment_id (required), +1 more. Returns: result
search_codeB
Search code across GitHub repositories.
Inputs: query (required), per_page, page. Returns: result
search_issuesB
Search issues and pull requests across GitHub.
Inputs: query (required), sort, order, per_page, +1 more. Returns: result
search_repositoriesC
Search GitHub repositories.
Inputs: query (required), sort, order, per_page, +1 more. Returns: result
search_usersB
Search GitHub users.
Inputs: query (required), sort, order, per_page, +1 more. Returns: result
star_repositoryB
Star a repository.
Inputs: owner (required), repo (required). Returns: result
trigger_workflowB
Trigger a workflow dispatch event to run a workflow.
Inputs: owner (required), repo (required), workflow_id (required), ref (required), +1 more. Returns: result
unstar_repositoryC
Unstar a repository.
Inputs: owner (required), repo (required). Returns: result
update_branch_protectionC
Update branch protection rules for a branch.
Inputs: owner (required), repo (required), branch (required), required_status_checks_strict, +12 more. Returns: result
update_gistB
Update an existing gist. Provide files to add/update, or set a filename's content to empty string to delete it.
Inputs: gist_id (required), description, files. Returns: result
update_issueC
Update an existing issue.
Inputs: owner (required), repo (required), issue_number (required), title, +4 more. Returns: result
update_pull_requestC
Update a pull request.
Inputs: owner (required), repo (required), pull_number (required), title, +3 more. Returns: result
update_pull_request_branchA
Update a pull request branch with the latest changes from the base branch. This is equivalent to pressing the 'Update branch' button on GitHub.
Inputs: owner (required), repo (required), pull_number (required), expected_head_sha. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 87 tools
Each tool has a clearly distinct purpose targeting specific resources and actions, such as create_issue vs. update_issue or list_branches vs. delete_branch. The descriptions are precise, and there is no significant overlap that would cause misselection, even with many tools.
All tool names follow a consistent verb_noun pattern with snake_case throughout, such as create_repository, list_commits, and update_branch_protection. There are no deviations in naming conventions, making the set highly predictable and readable.
With 87 tools, the count is excessive for typical MCP server purposes, making it overwhelming and heavy for agents to navigate. While GitHub is a broad platform, this many tools likely includes niche operations that could be consolidated or omitted for better usability.
The tool set provides comprehensive coverage of GitHub's API, including CRUD operations for repositories, issues, pull requests, branches, and more, plus advanced features like webhooks, workflows, and searches. There are no obvious gaps, and agents can handle full lifecycle management within the domain.
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLM agents to manage GitHub repositories, issues, pull requests, branches, files, and releases through a standardized interface.443 npm8Apache 2.0
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants to perform GitHub operations including repository management, file operations, issue tracking, and pull request creation.2-
- FlicenseNot gradedqualityNot gradedmaintenanceModel Context Protocol server that enables interaction with GitHub repositories, issues, pull requests, and search functionality through natural language.1-
- -licenseCqualityNot gradedmaintenanceA Model Context Protocol server with GitHub API integration that enables interaction with repositories, issues, pull requests, and file management through a standardized interface.1-