Which integrations are available for this 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.

How do I use GitHub MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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)

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

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.

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