📌Overview

Purpose: To facilitate seamless interactions with the GitHub API, enabling efficient file operations, repository management, and advanced search functionalities.

Overview: The GitHub MCP Server provides a comprehensive interface that integrates with the GitHub API, enhancing productivity through automated branch management, error handling, and maintaining Git history. It supports a wide array of operations related to repositories, files, issues, and pull requests, empowering developers to streamline their workflow.

Key Features:

Automatic Branch Creation: Automatically generates branches when creating or updating files, ensuring that changes are organized and do not disrupt existing workflows.
Comprehensive Error Handling: Offers explicit error messages for common issues, aiding developers in quickly resolving problems during integrations.
Git History Preservation: Ensures all operations maintain a proper Git history, avoiding the drawbacks of force pushes and safeguarding the integrity of the codebase.
Batch Operations: Supports the ability to handle single-file and multi-file operations together, significantly improving efficiency in file management.
Advanced Search: Allows users to search through code, issues, pull requests, and users, making it easier to navigate and manage large repositories effectively.

GitHub MCP Server

Deprecation Notice: Development for this project has been moved to GitHub in the http://github.com/github/github-mcp-server repo.

MCP Server for the GitHub API, enabling file operations, repository management, search functionality, and more.

Features

Automatic branch creation when files are created/updated or changes pushed, if branches do not exist.
Comprehensive error handling with clear messages.
Git history preservation without force pushing.
Support for batch operations (single-file and multi-file).
Advanced search for code, issues/PRs, and users.

Tools

create_or_update_file
Create or update a single file in a repository.
Inputs: owner, repo, path, content, message, branch, sha (optional)
Returns: File content and commit details.
push_files
Push multiple files in a single commit.
Inputs: owner, repo, branch, files (path, content), message
Returns: Updated branch reference.
search_repositories
Search for GitHub repositories.
Inputs: query, page (optional), perPage (optional)
Returns: Repository search results.
create_repository
Create a new GitHub repository.
Inputs: name, description (optional), private (optional), autoInit (optional)
Returns: Created repository details.
get_file_contents
Get contents of a file or directory.
Inputs: owner, repo, path, branch (optional)
Returns: File/directory contents.
create_issue
Create a new issue.
Inputs: owner, repo, title, body (optional), assignees (optional), labels (optional), milestone (optional)
Returns: Created issue details.
create_pull_request
Create a new pull request.
Inputs: owner, repo, title, body (optional), head, base, draft (optional), maintainer_can_modify (optional)
Returns: Created pull request details.
fork_repository
Fork a repository.
Inputs: owner, repo, organization (optional)
Returns: Forked repository details.
create_branch
Create a new branch.
Inputs: owner, repo, branch, from_branch (optional)
Returns: Created branch reference.
list_issues
List and filter repository issues.
Inputs include owner, repo, state, labels, sort, direction, since, page, per_page (all optional except owner and repo)
Returns: Array of issue details.
update_issue
Update an existing issue.
Inputs: owner, repo, issue_number, and optional fields for title, body, state, labels, assignees, milestone
Returns: Updated issue details.
add_issue_comment
Add a comment to an issue.
Inputs: owner, repo, issue_number, body
Returns: Created comment details.
search_code
Search code across GitHub repositories.
Inputs: q (query), sort (optional), order (optional), per_page (optional), page (optional)
Returns: Code search results.
search_issues
Search issues and pull requests.
Inputs: q (query), sort (optional), order (optional), per_page (optional), page (optional)
Returns: Issue and PR search results.
search_users
Search GitHub users.
Inputs: q (query), sort (optional), order (optional), per_page (optional), page (optional)
Returns: User search results.
list_commits
Get commits of a branch.
Inputs: owner, repo, page (optional), per_page (optional), sha (optional)
Returns: List of commits.
get_issue
Retrieve contents of an issue.
Inputs: owner, repo, issue_number
Returns: Issue details.
get_pull_request
Get details of a specific pull request.
Inputs: owner, repo, pull_number
Returns: Pull request details including diff and review status.
list_pull_requests
List and filter pull requests.
Inputs: owner, repo, state, head, base, sort, direction, per_page, page (all optional except owner and repo)
Returns: Array of pull request details.
create_pull_request_review
Create a review on a pull request.
Inputs: owner, repo, pull_number, body, event, commit_id (optional), comments (optional)
Returns: Created review details.
merge_pull_request
Merge a pull request.
Inputs: owner, repo, pull_number, commit_title (optional), commit_message (optional), merge_method (optional)
Returns: Merge result details.
get_pull_request_files
Get the list of files changed in a pull request.
Inputs: owner, repo, pull_number
Returns: Changed files with patch and status.
get_pull_request_status
Get combined status of status checks for a pull request.
Inputs: owner, repo, pull_number
Returns: Combined status check results and individual check details.
update_pull_request_branch
Update a pull request branch with latest changes from base branch.
Inputs: owner, repo, pull_number, expected_head_sha (optional)
Returns: Success message.
get_pull_request_comments
Get review comments on a pull request.
Inputs: owner, repo, pull_number
Returns: Array of review comments with details.
get_pull_request_reviews
Get reviews on a pull request.
Inputs: owner, repo, pull_number
Returns: Array of reviews with states and details.

Search Query Syntax

Code Search

language:javascript — filter by programming language
repo:owner/name — filter by repository
path:app/src — filter by path
extension:js — filter by file extension
Example: q: "import express" language:typescript path:src/

Issues Search

is:issue or is:pr — filter by type
is:open or is:closed — filter by state
label:bug — filter by label
author:username — filter by author
Example: q: "memory leak" is:issue is:open label:bug

Users Search

type:user or type:org — filter by account type
followers:>1000 — filter by number of followers
location:London — filter by location
Example: q: "fullstack developer" location:London followers:>100

For detailed search syntax, see GitHub's searching documentation at https://docs.github.com/en/search-github/searching-on-github.

Setup

Personal Access Token

Create a GitHub Personal Access Token with appropriate permissions:

Go to Personal access tokens in GitHub Settings > Developer settings
Select repository access (Public, All, or Select)
Create a token with the repo scope (full control for private repositories)
- Or public_repo scope for public repositories only
Copy the generated token

Usage with Claude Desktop

Add the following to claude_desktop_config.json to configure MCP server usage.

Docker

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "mcp/github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Build

Build Docker image with:

docker build -t mcp/github -f src/github/Dockerfile .

License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License. See the LICENSE file in the project repository for details.