GitHub MCP Server

The GitHub MCP Server connects AI tools directly to GitHub’s platform. This gives AI agents, assistants, and chatbots the ability to read repositories and code files, manage issues and PRs, analyze code, and automate workflows. All through natural language interactions.

Use Cases

• Repository Management: Browse and query code, search files, analyze commits, and understand project structure across any repository you have access to.
• Issue & PR Automation: Create, update, and manage issues and pull requests. Let AI help triage bugs, review code changes, and maintain project boards.
• CI/CD & Workflow Intelligence: Monitor GitHub Actions workflow runs, analyze build failures, manage releases, and get insights into your development pipeline.
• Code Analysis: Examine security findings, review Dependabot alerts, understand code patterns, and get comprehensive insights into your codebase.
• Team Collaboration: Access discussions, manage notifications, analyze team activity, and streamline processes for your team.

Built for developers who want to connect their AI tools to GitHub context and capabilities, from simple natural language queries to complex multi-step agent workflows.

Using the Go module

The Go module path is github.com/github/github-mcp-server/v2. Library consumers must use this prefix in imports, for example github.com/github/github-mcp-server/v2/pkg/github, and in go get commands. No /v2 subdirectory is needed when building from a repository checkout.

The existing v2.0.0 tag predates this module-path correction and cannot be used as a Go module. After this change is merged, a new release such as v2.0.1 must be tagged from a commit containing the corrected module path. Until then, consumers can use a pseudo-version from a commit containing this change.

---

Remote GitHub MCP Server

The remote GitHub MCP Server is hosted by GitHub and provides the easiest method for getting up and running. If your MCP host does not support remote MCP servers, don’t worry! You can use the local version of the GitHub MCP Server instead.

Prerequisites

1. A compatible MCP host with remote server support (VS Code 1.101+, Claude Desktop, Cursor, Windsurf, etc.)
2. Any applicable policies enabled

Install in VS Code

For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start. Make sure you’re using VS Code 1.101 or later for remote MCP and OAuth support.

Alternatively, to manually configure VS Code, choose the appropriate JSON block from the examples below and add it to your host configuration:

Install in other MCP hosts

• Copilot CLI - Installation guide for GitHub Copilot CLI
• GitHub Copilot in other IDEs - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
• Claude Applications - Installation guide for Claude Desktop and Claude Code CLI
• Codex - Installation guide for OpenAI Codex
• Cursor - Installation guide for Cursor IDE
• OpenCode - Installation guide for the OpenCode terminal agent
• Windsurf - Installation guide for Windsurf IDE
• Zed - Installation guide for Zed editor
• Rovo Dev CLI - Installation guide for Rovo Dev CLI

Note: Each MCP host application needs to configure a GitHub App or OAuth App to support remote access via OAuth. Any host application that supports remote MCP servers should support the remote GitHub server with PAT authentication. Configuration details and support levels vary by host. Make sure to refer to the host application’s documentation for more info.

Configuration

Toolset configuration

See Remote Server Documentation for full details on remote server configuration, toolsets, headers, and advanced usage. This file provides comprehensive instructions and examples for connecting, customizing, and installing the remote GitHub MCP Server in VS Code and other MCP hosts.

When no toolsets are specified, default toolsets are used.

Insiders Mode

Try new features early! The remote server offers an insiders version with early access to new features and experimental tools.

See Remote Server Documentation for more details and examples, and Insiders Features for a full list of what’s available.

GitHub Enterprise

GitHub Enterprise Cloud with data residency (ghe.com)

GitHub Enterprise Cloud can also make use of the remote server.

Example for https://octocorp.ghe.com with GitHub PAT token:

{
    ...
    "github-octocorp": {
      "type": "http",
      "url": "https://copilot-api.octocorp.ghe.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}"
      }
    },
    ...
}

Note: When using OAuth with GitHub Enterprise with VS Code and GitHub Copilot, you also need to configure your VS Code settings to point to your GitHub Enterprise instance - see Authenticate from VS Code

GitHub Enterprise Server

GitHub Enterprise Server does not support remote server hosting. Please refer to GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com) from the local server configuration.

---

Local GitHub MCP Server

Prerequisites

1. To run the server in a container, you will need to have Docker installed.

2. Once Docker is installed, you will also need to ensure Docker is running. The Docker image is available at ghcr.io/github/github-mcp-server. The image is public; if you get errors on pull, you may have an expired token and need to docker logout ghcr.io.

3. Authentication. On github.com you don’t need to create anything up front — the one-click buttons above log you in with OAuth on first use (a browser-based flow; the token is kept in memory only). The Docker buttons publish a fixed callback port (127.0.0.1:8085) so the container’s login callback is reachable. See Local Server OAuth Login for how it works, headless/device-code fallback, and bringing your own OAuth or GitHub App (required for GitHub Enterprise Server and ghe.com).

   Prefer a token? You can still authenticate with a GitHub Personal Access Token by setting GITHUB_PERSONAL_ACCESS_TOKEN instead (it takes precedence over OAuth). The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the documentation).

GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com)

The flag --gh-host and the environment variable GITHUB_HOST can be used to set the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data residency.

• For GitHub Enterprise Server, prefix the hostname with the https:// URI scheme. HTTPS is required and enforced: non-HTTPS hosts are refused so that credentials are never sent over cleartext (the only exception is a loopback host such as http://localhost for local development).
• For GitHub Enterprise Cloud with data residency, use https://YOURSUBDOMAIN.ghe.com as the hostname.

"github": {
    "command": "docker",
    "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "-e",
    "GITHUB_HOST",
    "ghcr.io/github/github-mcp-server"
    ],
    "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
        "GITHUB_HOST": "https://"
    }
}

Installation

Install in GitHub Copilot on VS Code

For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start.

More about using MCP server tools in VS Code’s agent mode documentation.

Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.)

Add one of the following JSON blocks to your IDE’s MCP settings.

Log in with OAuth (no token to create or store). On github.com the official image already includes the app credentials, so you provide none yourself: it runs a browser-based login on first use and keeps the resulting token in memory only. In Docker this needs a fixed callback port published to loopback so the container’s login callback is reachable:

{
  "mcp": {
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-p",
          "127.0.0.1:8085:8085",
          "-e",
          "GITHUB_OAUTH_CALLBACK_PORT",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_OAUTH_CALLBACK_PORT": "8085"
        }
      }
    }
  }
}

See Local Server OAuth Login for the native-binary flow (no fixed port needed), the headless/device-code fallback, GitHub Enterprise Server / ghe.com, and bringing your own OAuth or GitHub App.

For non-interactive stdio deployments, see GitHub App Authentication.

Or authenticate with a Personal Access Token. Set GITHUB_PERSONAL_ACCESS_TOKEN instead (it takes precedence over OAuth):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "github_token",
        "description": "GitHub Personal Access Token",
        "password": true
      }
    ],
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
        }
      }
    }
  }
}

Optionally, you can add a similar example (i.e. without the mcp key) to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with other host applications that accept the same format.

Install in Other MCP Hosts

For other MCP host applications, please refer to our installation guides:

• Copilot CLI - Installation guide for GitHub Copilot CLI
• GitHub Copilot in other IDEs - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
• Claude Code & Claude Desktop - Installation guide for Claude Code and Claude Desktop
• Cursor - Installation guide for Cursor IDE
• Google Gemini CLI - Installation guide for Google Gemini CLI
• OpenCode - Installation guide for the OpenCode terminal agent
• Windsurf - Installation guide for Windsurf IDE
• Zed - Installation guide for Zed editor

For a complete overview of all installation options, see our Installation Guides Index.

Note: Any host application that supports local MCP servers should be able to access the local GitHub MCP server. However, the specific configuration process, syntax and stability of the integration will vary by host application. While many may follow a similar format to the examples above, this is not guaranteed. Please refer to your host application’s documentation for the correct MCP configuration syntax and setup process.

Build from source

If you don’t have Docker, you can use go build to build the binary in the cmd/github-mcp-server directory, and use the github-mcp-server stdio command with the GITHUB_PERSONAL_ACCESS_TOKEN environment variable set to your token. To specify the output location of the build, use the -o flag. You should configure your server to use the built executable as its command.

STDIO API requests identify the server as github-mcp-server/ and retain the upstream MCP client’s name/version in parentheses when available. Control characters, quotes, backslashes and parentheses in client metadata are escaped so the HTTP header remains valid; ordinary names, versions, spaces and printable Unicode are preserved. Release builds keep their release version. Source and default Docker builds with revision metadata use vcs-. The Docker publishing workflow preserves tag versions, including prereleases, and lets branch, pull-request and nightly builds use the linked source revision. The -dirty marker applies only when both the revision and modified state come from embedded VCS metadata, never to a valid, explicitly supplied main.commit. This is a VCS build identifier, not a release number.

Build the complete package with go build -o github-mcp-server ./cmd/github-mcp-server from a Git checkout to embed its VCS revision. For builds without VCS metadata, supply the actual release with -ldflags '-X main.version=' or the full source revision with -ldflags '-X main.commit='. Valid metadata is selected in this order: explicit release, explicit source revision, embedded VCS revision, then installed main-module version. Valid explicit revisions remain authoritative even if build-context filtering changes embedded VCS metadata. Missing or malformed candidates fall through to the next usable source. If none is available, STDIO still starts with the development label dev and emits a warning on stderr, leaving stdout available for the MCP protocol. Supply real release or revision metadata when version-specific attribution is needed.

For example:

{
  "mcp": {
    "servers": {
      "github": {
        "command": "/path/to/github-mcp-server",
        "args": ["stdio"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": ""
        }
      }
    }
  }
}

Tool Configuration

The GitHub MCP Server supports enabling or disabling specific groups of functionalities via the --toolsets flag. This allows you to control which GitHub API capabilities are available to your AI tools. Enabling only the toolsets that you need can help the LLM with tool choice and reduce the context size.

Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also included where applicable.

When no toolsets are specified, default toolsets are used.

Looking for examples? See the Server Configuration Guide for common recipes like minimal setups, read-only mode, and combining tools with toolsets.

Specifying Toolsets

To specify toolsets you want available to the LLM, you can pass an allow-list in two ways:

1. Using Command Line Argument:

   github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security
   

2. Using Environment Variable:

   GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server
   

The environment variable GITHUB_TOOLSETS takes precedence over the command line argument if both are provided.

Specifying Individual Tools

You can also configure specific tools using the --tools flag. Tools can be used independently or combined with toolsets for fine-grained control.

1. Using Command Line Argument:

   github-mcp-server --tools get_file_contents,issue_read,create_pull_request
   

2. Using Environment Variable:

   GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" ./github-mcp-server
   

3. Combining with Toolsets (additive):

   github-mcp-server --toolsets repos,issues --tools get_gist
   

   This registers all tools from repos and issues toolsets, plus get_gist.

Important Notes:

• Tools and toolsets can be used together
• Read-only mode takes priority: write tools are skipped if --read-only is set, even if explicitly requested via --tools
• Tool names must match exactly (e.g., get_file_contents, not getFileContents). Invalid tool names will cause the server to fail at startup with an error message
• When tools are renamed, old names are preserved as aliases for backward compatibility. See Tool Renaming for details.

Using Toolsets With Docker

When using Docker, you can pass the toolsets as environment variables:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" \
  ghcr.io/github/github-mcp-server

Using Tools With Docker

When using Docker, you can pass specific tools as environment variables. You can also combine tools with toolsets:

# Tools only
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" \
  ghcr.io/github/github-mcp-server

# Tools combined with toolsets (additive)
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_TOOLSETS="repos,issues" \
  -e GITHUB_TOOLS="get_gist" \
  ghcr.io/github/github-mcp-server

Special toolsets

“all” toolset

The special toolset all can be provided to enable all available toolsets regardless of any other configuration:

./github-mcp-server --toolsets all

Or using the environment variable:

GITHUB_TOOLSETS="all" ./github-mcp-server

“default” toolset

The default toolset default is the configuration that gets passed to the server if no toolsets are specified.

The default configuration is:

• context
• repos
• issues
• pull_requests
• users

To keep the default configuration and add additional toolsets:

GITHUB_TOOLSETS="default,stargazers" ./github-mcp-server

Insiders Mode

The local GitHub MCP Server offers an insiders version with early access to new features and experimental tools.

1. Using Command Line Argument:

   ./github-mcp-server --insiders
   

2. Using Environment Variable:

   GITHUB_INSIDERS=true ./github-mcp-server
   

When using Docker:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_INSIDERS=true \
  ghcr.io/github/github-mcp-server

Available Toolsets

The following sets of tools are available:

Additional Toolsets in Remote GitHub MCP Server

Tools

Repository tools expose output schemas and typed structuredContent when the negotiated MCP protocol version is a supported version 2026-07-28 or newer. Older clients, clients with an unknown protocol version, and clients omitting the version receive the existing content without an output schema or structured output. Unknown versions are not treated as supported merely because they sort after 2026-07-28.

For get_file_contents, directory results (including field projections) are structured arrays. File downloads and metadata-only responses use a content array of typed text, embedded-resource, or resource-link blocks, preserving status messages, text, base64 blobs, empty files, and download links. Text-only repository mutations such as starring and deletion also return a structured message; fork responses distinguish a repository reference from an in-progress message. Repository deletion still requires its existing confirmation flow before returning a completed result.

Structured repository results use compact DTOs rather than raw REST objects. Release lookups share the compact release shape with release listings; Git references retain the ref, object type, and SHA; annotated tags retain tag/message/tagger/target information; deletion commits retain SHA, message, authors, tree SHA, parent SHAs, and a human-facing html_url when available. Directory entries retain file metadata and useful HTML/download links, but omit API and hypermedia routing URLs even when those fields were requested in a projection. Legacy and unknown protocol versions retain the original text byte-for-byte; modern text-only JSON responses serialize the same compact DTO as structuredContent. Non-text resource blocks and tool errors retain their existing content behavior. Structured projections use the same sanitized and filtered source as the legacy formatter.

For get_repository_tree, list_gists, get_gist, create_gist, and update_gist, gist results retain file names, contents, sizes, language/type information, timestamps, visibility, and compact owner profiles, while omitting API/node and Git transport URLs. Tree entries omit their derivable API URLs. Create/update gist results contain the gist ID and HTML URL. Modern JSON text and structured content serialize the same compact result. Older or unknown protocol versions retain byte-for-byte legacy text without an output schema or structured content.

The issue metadata (list_issue_types, list_issue_fields), comment (add_issue_comment, update_issue_comment), dependency (issue_dependency_read, issue_dependency_write), and duplicate-detection (find_duplicate) tools provide typed outputSchema and structuredContent for negotiated supported protocol versions 2026-07-28 or newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.

For negotiated supported protocol versions 2026-07-28 or newer, the consolidated Actions tools (actions_list, actions_get, actions_run_trigger) return structured objects with a method discriminant and a method-specific typed field; JSON text contains the same compact projection. Workflow, job, and artifact projections omit API/hypermedia URLs while retaining browser links and useful identifiers, states, timestamps, and usage durations. Run usage lists billable runner environments in deterministic name order. Older and unknown-protocol text responses remain unchanged; get_job_logs retains its typed content, URL, or failed-job collection variants.

Additional Tools in Remote GitHub MCP Server

Read-Only Mode

To run the server in read-only mode, you can use the --read-only flag. This will only offer read-only tools, preventing any modifications to repositories, issues, pull requests, etc.

./github-mcp-server --read-only

When using Docker, you can pass the read-only mode as an environment variable:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_READ_ONLY=1 \
  ghcr.io/github/github-mcp-server

Lockdown Mode

Lockdown mode limits the content that the server will surface from public repositories. When enabled, the server checks whether the author of each item has push access to the repository. Private repositories are unaffected, and collaborators keep full access to their own content.

Lockdown mode is a best-effort content filter intended to reduce the risk of prompt injection from untrusted repository content (issues, pull requests, comments, commits, etc.). It is not an authorization boundary: it does not change what the underlying GitHub credential can read or write, and content withheld from a filtered tool response may still be reachable through other tools or direct GitHub API access with the same credential.

As an intentional exception, content authored by a small set of trusted bot accounts (currently github-actions[bot] and copilot) is always treated as safe, regardless of push access. This avoids filtering routine automation output (e.g. CI-generated commits or comments) that would otherwise be withheld under lockdown mode.

./github-mcp-server --lockdown-mode

When running with Docker, set the corresponding environment variable:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_LOCKDOWN_MODE=1 \
  ghcr.io/github/github-mcp-server

In HTTP mode, this flag (or GITHUB_LOCKDOWN_MODE) is an upper bound: the X-MCP-Lockdown request header can enable lockdown mode when the operator has not, but it cannot disable lockdown mode the operator has already enabled. See the Server Configuration Guide for details.

The behavior of lockdown mode depends on the tool invoked.

Following tools will return an error when the author lacks the push access:

• issue_read:get
• pull_request_read:get
• pull_request_read:get_diff
• pull_request_read:get_files
• pull_request_read:get_commits

Following tools will filter out content from users lacking the push access:

• issue_read:get_comments
• issue_read:get_sub_issues
• pull_request_read:get_comments
• pull_request_read:get_review_comments
• pull_request_read:get_reviews

i18n / Overriding Descriptions

The descriptions of the tools can be overridden by creating a github-mcp-server-config.json file in the same directory as the binary.

The file should contain a JSON object with the tool names as keys and the new descriptions as values. For example:

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
  "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
}

You can create an export of the current translations by running the binary with the --export-translations flag.

This flag will preserve any translations/overrides you have made, while adding any new translations that have been added to the binary since the last time you exported.

./github-mcp-server --export-translations
cat github-mcp-server-config.json

You can also use ENV vars to override the descriptions. The environment variable names are the same as the keys in the JSON file, prefixed with GITHUB_MCP_ and all uppercase.

For example, to override the TOOL_ADD_ISSUE_COMMENT_DESCRIPTION tool, you can set the following environment variable:

export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"

Overriding Server Name and Title

The same override mechanism can be used to customize the MCP server’s name and title fields in the initialization response. This is useful when running multiple GitHub MCP Server instances (e.g., one for github.com and one for GitHub Enterprise Server) so that agents can distinguish between them.

For example, to configure a server instance for GitHub Enterprise Server:

{
  "SERVER_NAME": "ghes-mcp-server",
  "SERVER_TITLE": "GHES MCP Server"
}

Or using environment variables:

export GITHUB_MCP_SERVER_NAME="ghes-mcp-server"
export GITHUB_MCP_SERVER_TITLE="GHES MCP Server"

Library Usage

The exported Go API of this module should currently be considered unstable, and subject to breaking changes. In the future, we may offer stability; please file an issue if there is a use case where this would be valuable.

Contributing

Contributions are welcome. Before opening a pull request, please read the contributing guide for setup, testing, linting, and documentation generation instructions.

Support

For help using the GitHub MCP Server, see the support guide. If you have found a bug or want to request a feature, please search existing issues before opening a new one.

Security

Please do not report security vulnerabilities through public issues. Follow the instructions in the security policy to report vulnerabilities responsibly.

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.