GitHub MCP

The GitHub MCP server lets an AI agent work with GitHub: read code, search repos, open and update issues and pull requests, check Actions runs and read security alerts. GitHub hosts it at https://api.githubcopilot.com/mcp/, and you can also run it yourself with Docker. It is MIT licensed and free. We checked the README, install guides and repo on 31 October 2026.

Quick facts

At the time we looked, the repo showed about 396 open issues and pull requests combined. That is a busy tracker, which usually means a live project, but it also means some of the details below can shift. Check the release notes when you upgrade.

What it lets an agent do

The README lists five areas it is built for:

• Repository work: browse and query code, search files, read commits, understand the layout of a project.
• Issues and pull requests: create, update and manage them, triage bugs, review changes.
• Actions and releases: watch workflow runs, read failure logs, manage releases.
• Security: read code scanning, Dependabot and secret scanning alerts and security advisories.
• Team collaboration: discussions, notifications, project boards, organization and team lookups.

For a developer this replaces a lot of copy and paste. Instead of pasting a failing job log into a chat, you tell the agent which run failed and it fetches the log itself.

Install it in each agent

You have two routes. The remote server needs nothing installed and is the easy choice if your client supports remote MCP servers. The local server runs in Docker and suits clients without remote support or setups that must not call out to a hosted endpoint.

Create a fine-grained personal access token first (GitHub, Settings, Developer settings). Put it in an environment variable rather than a config file. We use GITHUB_PAT below.

Claude Code

Remote, using the form from GitHub's Claude guide:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  -H "Authorization: Bearer $GITHUB_PAT"

GitHub's guide also shows an add-json form:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

The guide warns that add-json can return Invalid input on Windows for an HTTP server. If you see that, use the --transport http form. It also notes that if you see missing required argument 'name', you should put the server name directly after claude mcp add.

Local, with Docker:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Add --scope user to make it available in every project, or --scope project to write it into a shared .mcp.json. Do not commit a token into that file. Run claude mcp list to confirm.

Cursor

Add this to .cursor/mcp.json in a project or ~/.cursor/mcp.json for everywhere, then restart Cursor:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

Cursor's docs support ${env:NAME} interpolation in mcp.json, so you can reference an environment variable instead of pasting the token.

Codex

GitHub's Codex guide gives a one-line command and a matching config:

codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"

The guide says the --bearer-token-env-var option is required for PAT access to the hosted server. The file is ~/.codex/config.toml. Inside the TUI, /mcp lists the tools Codex can see.

Gemini CLI

The guide recommends the extension route:

gemini extensions install https://github.com/github/github-mcp-server

You still need a token named GITHUB_MCP_PAT in your environment. Or configure the remote server by hand in ~/.gemini/settings.json:

{
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer $GITHUB_MCP_PAT"
      }
    }
  }
}

Project-level config goes in .gemini/settings.json. Restart the CLI after editing.

VS Code

VS Code 1.101 or newer supports remote MCP servers, per the README prerequisites. The README has an install button for both the remote and Docker routes, which signs you in with OAuth on first use. If you prefer to edit by hand, VS Code's format uses a top-level servers key with a type of http and the same URL. Mind that the portable .mcp.json format uses mcpServers instead.

Other hosts

The repo also ships guides for Copilot CLI, JetBrains, Visual Studio, Eclipse and Xcode with Copilot, OpenCode, Windsurf, Zed and Rovo Dev CLI. The README adds a caution: each host has to set up a GitHub App or OAuth App to support OAuth, so OAuth support varies by host. PAT access works anywhere remote servers do.

Compatibility at a glance

Toolsets: choose what the agent sees

Every tool you load takes space in the model's context and gives the agent one more thing it can do. The server groups its tools into toolsets so you can load only what a job needs.

The remote server adds copilot, copilot_spaces and github_support_docs_search. The remote tool create_pull_request_with_copilot hands a task to the Copilot coding agent.

To pick toolsets locally, pass a flag or an environment variable:

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

The environment variable wins if both are set. The README also lets you pick individual tools. On the remote server each toolset is its own URL, and the remote docs describe adding /readonly to get the read-only variant.

Some tools worth knowing by name: get_file_contents, search_code, list_commits, issue_read, issue_write, add_issue_comment, pull_request_read, create_pull_request, pull_request_review_write, merge_pull_request, actions_list, get_job_logs, list_code_scanning_alerts, list_dependabot_alerts and get_me.

Auth and permissions

OAuth or PAT. Remote OAuth depends on the host. Where it is not available, use a PAT. In the local server, the token variable takes precedence over OAuth.

Scopes. The README's security notes name repo for repository operations, read:packages for Docker image access and read:org for organization team access. GitHub's Codex guide lists workflow, project and gist as extras when you use those tools, and tells you to add scopes only when a tool call fails for lack of permission.

Fine-grained tokens. We would use a fine-grained token limited to the repositories the agent needs. The README links to the fine-grained token page. It also says to use different tokens for different projects, rotate them and keep them out of version control.

Token storage. The README recommends keeping the PAT in an environment variable, adding .env to .gitignore and restricting file permissions on any config that holds a token. It admits environment variable support varies: some hosts, Windsurf is named, require the token to be written into the config file.

Safety: read this before you merge anything

This server can write. With the default toolsets it can create and update issues, open and merge pull requests, push files and create branches. The repos toolset also includes delete_file and delete_repository, and the actions toolset includes actions_run_trigger. Whether those work depends on your token, but the agent will see them.

Four habits cover most of the risk:

1. Start read-only. Use --read-only, GITHUB_READ_ONLY=1, or the /readonly remote URL until you trust a workflow.
2. Trim toolsets. If the job is triage, load issues only.
3. Keep merges manual. Let the agent open the PR and write the description. You press merge.
4. Narrow the token. A token that can only reach one repository cannot damage the other fifty.

Prompt injection is the real threat. Issues, comments and PR descriptions are text anyone can write, and the agent reads them as input. Claude Code's MCP docs tell you to trust only servers you verify and warn that servers that fetch external content raise injection risk. GitHub's answer is lockdown mode, enabled with --lockdown-mode or GITHUB_LOCKDOWN_MODE=1. In public repositories it checks whether the author of an item has push access and filters or errors on content from people who do not. The README is plain about its limits: it is a best-effort filter, not an authorization boundary, and it does not change what your credential can read or write. A few trusted bot accounts, github-actions[bot] and copilot, always pass.

Real tasks with copy-ready prompts

Triage new issues

List open issues in OWNER/REPO labelled "needs-triage". For each one,
read the body and comments, then suggest a label and a one-line
reply. Do not post anything. Show me the list first.

Explain a failing CI run

The latest run of the "ci" workflow on branch fix/login failed. Get the
failed job's logs, quote the first error, and tell me which file and
line is most likely at fault. Do not push changes.

Write a pull request description

Compare my branch feature/search to main. Read the commits and the diff
with pull_request_read or get_commit, then draft a PR title and body
with a summary, test notes and a rollback line. Do not create the PR.

Security sweep

List open Dependabot alerts and code scanning alerts for OWNER/REPO.
Group them by severity and say which have a fixed version available.

Find where something lives

Search OWNER/REPO for uses of the function parseConfig. Group by
directory and tell me which callers pass a second argument.

For a review loop that uses these calls, see the code review subagent in our kit.

Limits and known issues

• A very large tool surface. With every toolset on, the agent sees dozens of tools. That costs context and can confuse tool choice. The default five toolsets are there for a reason.
• OAuth is host dependent. The README says each host must set up its own GitHub or OAuth app. Expect a PAT on some hosts.
• Config quirks. GitHub's own guides list a Windows add-json error and an argument-order error for claude mcp add. They are easy to fix once you know them.
• Lockdown is partial. It filters specific read paths such as issue_read and pull_request_read. It does not make a write-capable token harmless.
• Open feature requests. The tracker holds requests such as file attachments on issues (#738) and more issue field types (#2659). If you need something unusual, search before assuming it exists.
• Remote only extras. The Copilot tools exist only on the hosted server, not the local build.

Alternatives

The agent's own shell is the real competitor. A coding agent with gh installed can do most of what this server does, with a smaller context footprint and your existing login. The server earns its place when you want structured results, fine toolset control, or when the client has no shell.

Which agents it works best with

• Claude Code handles the remote server cleanly and keeps the token in an environment variable. It pairs well with a /review style command.
• Codex has a built-in bearer token option, which keeps the secret out of the file.
• Copilot in VS Code gets the smoothest OAuth experience, since the server and the host share a vendor.
• Cursor and Gemini CLI work with a PAT header. Keep the token out of a committed file.

Our take

We did not test this server for this page. What follows comes from the README and install guides.

The strongest point is the toolset design. Letting you load issues and nothing else is the difference between a focused assistant and one that can delete a repository by accident. The three controls, toolsets, read-only mode and a narrow fine-grained token, are all documented and all cheap to use.

The weak point is not the server. It is the habit of giving a write token to an agent that reads untrusted text. Issues and comments are an open door. Lockdown mode narrows it, and the README is honest that it does not close it.

Our rule of thumb for teams: start with the default toolsets on a read-only token, add write access one repository at a time, and keep merging human. If your agent already has a shell with gh, try that first and add this server when you need the structure.

Setup checklist

1. Create a fine-grained PAT for one repository.
2. Store it in GITHUB_PAT in your shell profile, not in a project file.
3. Add the remote server with the command for your agent.
4. Turn on /readonly or --read-only for the first week.
5. Run claude mcp list, codex mcp list or /mcp to confirm the server connected.
6. Ask for get_me first. It tells you whose identity the agent is using.
7. Add toolsets as you need them.

Frequently asked questions

Is there a hosted version of the GitHub MCP server? Yes, at https://api.githubcopilot.com/mcp/. Use OAuth where your host supports it, or a PAT header.

Which toolsets are on by default? context, repos, issues, pull_requests and users.

Can I make it read-only? Yes: --read-only, GITHUB_READ_ONLY=1, or /readonly on the remote URL.

What token scopes does it need? The README names repo, read:packages and read:org. Add workflow, project or gist only when you use those tools.

Does lockdown mode stop prompt injection? It reduces exposure in public repositories. The README says it is not an authorization boundary.

*Related: Context7 MCP, Playwright MCP, and the MCP servers hub. Product names are used descriptively. We are not affiliated with GitHub.*