Home / MCP / GitHub MCP Server

GitHub MCP Server

Exposes GitHub data and actions via MCP for repositories, issues, PRs, branches, commits, and file contents.

other

31stars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "github_mcp": {
            "command": "java",
            "args": [
                "-Dspring.ai.mcp.server.stdio=true",
                "-Dspring.main.web-application-type=none",
                "-Dlogging.pattern.console=",
                "-jar",
                "/path/to/GitHubMCP/target/GitHubMCP-1.0-SNAPSHOT.jar"
            ],
            "env": {
                "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN",
                "GITHUB_HOST": "github.com",
                "GITHUB_REPOSITORY": "your-username/your-repository"
            }
        }
    }
}

You run a GitHub MCP Server that exposes GitHub data and actions as MCP-compatible endpoints. This lets you safely harness the GitHub API from Large Language Models or other MCP clients to manage repositories, issues, pull requests, branches, commits, and repository contents with structured, controlled access.

How to use

You interact with the server through an MCP client. Start the local MCP server using the Java runtime and connect your client via STDIO if you are using a local workflow, or run it as a web server and connect over HTTP when you prefer a remote setup. You can perform common tasks like listing your repositories, reading and creating issues, commenting on pull requests, merging PRs, handling branches, and inspecting file contents. You can also override the default repository by specifying a target owner/repo on a per-request basis to work with multiple projects without changing the server configuration.

Your environment should provide a GitHub access token and optionally a specific GitHub host for Enterprise instances. The server uses these credentials to access the GitHub API on your behalf and perform the requested actions.

How to install

Prerequisites you need on your machine before starting the server:

Java 17 or higher

Maven 3.6+

A GitHub account and a personal access token

Steps to install and run the MCP server locally:

1) Build the project with Maven

mvn clean package

2) Run the MCP server as a standalone Java application

java -jar target/GitHubMCP-1.0-SNAPSHOT.jar

Configuration and usage notes

The server can operate in STDIO mode for direct MCP client communication or as a web server for HTTP-based access. To enable STDIO, you will typically use JVM system properties to configure the client communication mode and point to the built JAR. You also configure authentication via environment variables.

Environment variables to configure authentication and context (example values shown):

GITHUB_TOKEN=your-github-token-here
GITHUB_HOST=github.com
GITHUB_REPOSITORY=your-username/your-repository

Security considerations

Provide a GitHub personal access token with the minimum permissions required for your tasks. The MCP server will allow operations that read, create, or modify GitHub resources based on the token's scope. Run the server in a controlled environment and safeguard the token.

Examples and tips

If you configure the server with environment variables, you can ask the MCP client to perform tasks such as listing issues or pulling pull request details without repeatedly passing credentials. You can override the default repository in a request to operate across multiple projects.

Troubleshooting

If you encounter authentication errors, verify the GitHub token has the necessary scopes and that GITHUB_HOST is set correctly for GitHub.com or your Enterprise instance. Check that the server has network access to reach the GitHub API and that your token has not expired.

Available tools

listRepositories

List repositories for the authenticated user

getRepository

Get detailed information about a specific repository

searchRepositories

Search for repositories matching a query

listIssues

List issues for a repository with filtering options

getIssue

Get detailed information about a specific issue

createIssue

Create a new issue in a repository

addIssueComment

Add a comment to an issue

searchIssues

Search for issues matching a query

listPullRequests

List pull requests for a repository with filtering options

getPullRequest

Get detailed information about a specific pull request

createPullRequestComment

Add a comment to a pull request

mergePullRequest

Merge a pull request with a specified method

listBranches

List branches in a repository with filtering options

createBranch

Create a new branch from a specified reference

getCommitDetails

Get detailed information about a specific commit

listCommits

List commits in a repository with filtering options

findCommitByMessage

Search for commits containing specific text in their messages

getFileContents

Get the contents of a file in a repository

listDirectoryContents

List contents of a directory in a repository

createOrUpdateFile

Create or update a file in a repository

searchCode

Search for code within repositories