GitHub MCP Server
MCP Server for the GitHub API, enabling file operations, repository management, search functionality, and more.
Features
- Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
- Comprehensive Error Handling: Clear error messages for common issues
- Git History Preservation: Operations maintain proper Git history without force pushing
- Batch Operations: Support for both single-file and multi-file operations
- Advanced Search: Support for searching code, issues/PRs, and users
Tools
-
create_or_update_file- Create or update a single file in a repository
- Inputs:
owner(string): Repository owner (username or organization)repo(string): Repository namepath(string): Path where to create/update the filecontent(string): Content of the filemessage(string): Commit messagebranch(string): Branch to create/update the file insha(optional string): SHA of file being replaced (for updates)
- Returns: File content and commit details
-
push_files- Push multiple files in a single commit
- Inputs:
owner(string): Repository ownerrepo(string): Repository namebranch(string): Branch to push tofiles(array): Files to push, each withpathandcontentmessage(string): Commit message
- Returns: Updated branch reference
-
search_repositories- Search for GitHub repositories
- Inputs:
query(string): Search querypage(optional number): Page number for paginationperPage(optional number): Results per page (max 100)
- Returns: Repository search results
-
create_repository- Create a new GitHub repository
- Inputs:
name(string): Repository namedescription(optional string): Repository descriptionprivate(optional boolean): Whether repo should be privateautoInit(optional boolean): Initialize with README
- Returns: Created repository details
-
get_file_contents- Get contents of a file or directory
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepath(string): Path to file/directorybranch(optional string): Branch to get contents from
- Returns: File/directory contents
-
create_issue- Create a new issue
- Inputs:
owner(string): Repository ownerrepo(string): Repository nametitle(string): Issue titlebody(optional string): Issue descriptionassignees(optional string[]): Usernames to assignlabels(optional string[]): Labels to addmilestone(optional number): Milestone number
- Returns: Created issue details
-
create_pull_request- Create a new pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository nametitle(string): PR titlebody(optional string): PR descriptionhead(string): Branch containing changesbase(string): Branch to merge intodraft(optional boolean): Create as draft PRmaintainer_can_modify(optional boolean): Allow maintainer edits
- Returns: Created pull request details
-
fork_repository- Fork a repository
- Inputs:
owner(string): Repository ownerrepo(string): Repository nameorganization(optional string): Organization to fork to
- Returns: Forked repository details
-
create_branch- Create a new branch
- Inputs:
owner(string): Repository ownerrepo(string): Repository namebranch(string): Name for new branchfrom_branch(optional string): Source branch (defaults to repo default)
- Returns: Created branch reference
-
list_issues- List and filter repository issues
- Inputs:
owner(string): Repository ownerrepo(string): Repository namestate(optional string): Filter by state ('open', 'closed', 'all')labels(optional string[]): Filter by labelssort(optional string): Sort by ('created', 'updated', 'comments')direction(optional string): Sort direction ('asc', 'desc')since(optional string): Filter by date (ISO 8601 timestamp)page(optional number): Page numberper_page(optional number): Results per page
- Returns: Array of issue details
-
update_issue- Update an existing issue
- Inputs:
owner(string): Repository ownerrepo(string): Repository nameissue_number(number): Issue number to updatetitle(optional string): New titlebody(optional string): New descriptionstate(optional string): New state ('open' or 'closed')labels(optional string[]): New labelsassignees(optional string[]): New assigneesmilestone(optional number): New milestone number
- Returns: Updated issue details
-
add_issue_comment- Add a comment to an issue
- Inputs:
owner(string): Repository ownerrepo(string): Repository nameissue_number(number): Issue number to comment onbody(string): Comment text
- Returns: Created comment details
-
search_code- Search for code across GitHub repositories
- Inputs:
q(string): Search query using GitHub code search syntaxsort(optional string): Sort field ('indexed' only)order(optional string): Sort order ('asc' or 'desc')per_page(optional number): Results per page (max 100)page(optional number): Page number
- Returns: Code search results with repository context
-
search_issues- Search for issues and pull requests
- Inputs:
q(string): Search query using GitHub issues search syntaxsort(optional string): Sort field (comments, reactions, created, etc.)order(optional string): Sort order ('asc' or 'desc')per_page(optional number): Results per page (max 100)page(optional number): Page number
- Returns: Issue and pull request search results
-
search_users- Search for GitHub users
- Inputs:
q(string): Search query using GitHub users search syntaxsort(optional string): Sort field (followers, repositories, joined)order(optional string): Sort order ('asc' or 'desc')per_page(optional number): Results per page (max 100)page(optional number): Page number
- Returns: User search results
-
list_commits
- Gets commits of a branch in a repository
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepage(optional string): page numberper_page(optional string): number of record per pagesha(optional string): branch name
- Returns: List of commits
get_issue
- Gets the contents of an issue within a repository
- Inputs:
owner(string): Repository ownerrepo(string): Repository nameissue_number(number): Issue number to retrieve
- Returns: Github Issue object & details
get_pull_request
- Get details of a specific pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request number
- Returns: Pull request details including diff and review status
list_pull_requests
- List and filter repository pull requests
- Inputs:
owner(string): Repository ownerrepo(string): Repository namestate(optional string): Filter by state ('open', 'closed', 'all')head(optional string): Filter by head user/org and branchbase(optional string): Filter by base branchsort(optional string): Sort by ('created', 'updated', 'popularity', 'long-running')direction(optional string): Sort direction ('asc', 'desc')per_page(optional number): Results per page (max 100)page(optional number): Page number
- Returns: Array of pull request details
create_pull_request_review
- Create a review on a pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request numberbody(string): Review comment textevent(string): Review action ('APPROVE', 'REQUEST_CHANGES', 'COMMENT')commit_id(optional string): SHA of commit to reviewcomments(optional array): Line-specific comments, each with:path(string): File pathposition(number): Line position in diffbody(string): Comment text
- Returns: Created review details
merge_pull_request
- Merge a pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request numbercommit_title(optional string): Title for merge commitcommit_message(optional string): Extra detail for merge commitmerge_method(optional string): Merge method ('merge', 'squash', 'rebase')
- Returns: Merge result details
get_pull_request_files
- Get the list of files changed in a pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request number
- Returns: Array of changed files with patch and status details
get_pull_request_status
- Get the combined status of all status checks for a pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request number
- Returns: Combined status check results and individual check details
update_pull_request_branch
- Update a pull request branch with the latest changes from the base branch (equivalent to GitHub's "Update branch" button)
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request numberexpected_head_sha(optional string): The expected SHA of the pull request's HEAD ref
- Returns: Success message when branch is updated
get_pull_request_comments
- Get the review comments on a pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request number
- Returns: Array of pull request review comments with details like the comment text, author, and location in the diff
get_pull_request_reviews
- Get the reviews on a pull request
- Inputs:
owner(string): Repository ownerrepo(string): Repository namepull_number(number): Pull request number
- Returns: Array of pull request reviews with details like the review state (APPROVED, CHANGES_REQUESTED, etc.), reviewer, and review body
Search Query Syntax
Code Search
language:javascript: Search by programming languagerepo:owner/name: Search in specific repositorypath:app/src: Search in specific pathextension:js: Search by file extension- Example:
q: "import express" language:typescript path:src/
Issues Search
is:issueoris:pr: Filter by typeis:openoris:closed: Filter by statelabel:bug: Search by labelauthor:username: Search by author- Example:
q: "memory leak" is:issue is:open label:bug
Users Search
type:userortype:org: Filter by account typefollowers:>1000: Filter by followerslocation:London: Search by location- Example:
q: "fullstack developer" location:London followers:>100
For detailed search syntax, see GitHub's searching documentation.
Setup
Personal Access Token
Create a GitHub Personal Access Token with appropriate permissions:
- Go to Personal access tokens (in GitHub Settings > Developer settings)
- Select which repositories you'd like this token to have access to (Public, All, or Select)
- Create a token with the
reposcope ("Full control of private repositories")- Alternatively, if working only with public repositories, select only the
public_reposcope
- Alternatively, if working only with public repositories, select only the
- Copy the generated token
Usage with Claude Desktop
To use this with Claude Desktop, add the following to your claude_desktop_config.json:
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
Docker build:
docker build -t mcp/github -f src/github/Dockerfile .
License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.