Claude and the GitHub MCP Server: Issues, PRs and Projects

GitHub’s official MCP server, github/github-mcp-server, is hosted by GitHub at https://api.githubcopilot.com/mcp/. To use it from Claude Code, add it as an HTTP server with a GitHub personal access token in the Authorization header; GitHub’s own Claude guide↗ (opens in a new tab) uses a token because browser sign-in to the hosted server needs the client to have registered an app with GitHub. By default you get the context, repositories, issues, pull requests and users toolsets. GitHub Projects is a separate toolset you switch on, and the whole server can be made read-only with a different address or a header. The rest of this guide shows each setting.

There is also a local version of the same server, run with Docker or as a binary, which can sign you in through the browser. Both are covered below. If MCP itself is new to you, start with what MCP is.

Step 1: make a token

Create a personal access token under your GitHub settings. GitHub’s governance guide↗ (opens in a new tab) recommends fine-grained tokens over classic ones, and its README asks you to grant only what you are comfortable handing to an AI tool. A fine-grained token can be limited to chosen repositories. If you use a classic token, the server’s tool reference lists the scope each tool asks for: repo for issues and pull requests, read:project to read Projects and project to change them.

Organisations can restrict or require approval for tokens through their PAT policies, and single sign-on applies to tokens that reach SSO-protected organisations. If a token works on your own repositories but not your company’s, that is the first place to look.

Step 2: add the server to Claude Code

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

This is the form in Claude Code’s own documentation↗ (opens in a new tab). GitHub’s guide gives the same thing as claude mcp add-json for newer Claude Code versions and notes that on Windows add-json can answer Invalid input, in which case this form works. Run claude mcp list or /mcp afterwards to check the server is connected.

Pasting the token into a command stores it in ~/.claude.json. To share the setup with a team without sharing a token, put it in .mcp.json at the project root and let Claude Code read the token from each person’s environment; it expands ${VAR} in url and headers.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}",
        "X-MCP-Toolsets": "context,repos,issues,pull_requests,users,projects"
      }
    }
  }
}

Step 3: choose toolsets

The server groups its tools into toolsets. The defaults are context, repos, issues, pull_requests and users. Others include actions, code_security, dependabot, discussions, gists, labels, notifications, orgs, projects, secret_protection and security_advisories, and all turns everything on. GitHub’s advice↗ (opens in a new tab) is to enable only what you need, which helps the model pick the right tool and keeps the context smaller. On the hosted server you choose them in one of two ways:

• The X-MCP-Toolsets header, a comma-separated list, as in the .mcp.json above. Leave it out for the defaults.
• The address. /x/projects exposes one toolset only↗ (opens in a new tab) (one per address, not a list), and /x/all exposes everything.

An X-MCP-Tools header narrows further, to named tools only. An invalid tool name is an error, so copy names from the server’s tool reference.

Read-only mode

Point Claude Code at https://api.githubcopilot.com/mcp/readonly, or send the header X-MCP-Readonly: true, and only read tools are offered. It combines with a toolset: /x/projects/readonly gives Projects tools that can look but not change. On the local server the equivalent is the --read-only flag, and the README says read-only wins even over tools you name explicitly. For a first week with any assistant, a read-only connection and a narrow token is a sensible start.

GitHub Projects

With the projects toolset on, Claude Code gets three tools: projects_list, projects_get and projects_write. Between them they list projects, fields, views, items and status updates; read a single item with chosen fields; and add issues or pull requests to a project, update a field on one item or up to 50 items per call, create projects, iteration fields and views, and post status updates. Field values can be given by name, such as Status or Priority, rather than by ID. Prompts that work well:

• “List the items in project 7 of the acme organisation with their Status and Priority.”
• “Add issue 412 in acme/payments to project 7 and set Status to Next.”
• “Move every item in project 7 whose linked pull request has merged to Done.” This uses the pull request tools as well.
• “Write a project status update for project 7: on track, with a two-line summary of what closed this week.”

Issues and pull requests

The default toolsets cover the everyday work. Useful first prompts: “Which issues assigned to me in acme/payments are open, oldest first?”, “Summarise pull request 88 and its review comments”, and one write you can check: “Open an issue titled ‘Retry job double-charges on timeout’ with these steps and the bug label.” Keep merges and pushes for later.

Permissions and safety

The server enforces GitHub’s own permission model: according to GitHub’s governance guide, nobody can reach more through MCP than their credential already allows through the API, and underlying API calls appear in GitHub’s audit log where available. With a token, that credential is you, so changes appear under your name.

Claude Code adds its own layer. In its default mode it asks before an MCP tool call, and you can pre-approve reads with rules↗ (opens in a new tab) such as mcp__github__issue_read or mcp__github__projects_list. Keep issue_write, projects_write, merge_pull_request and push_files on ask.

Public repositories carry text anyone can write, which is a route for prompt injection; the documented case is in MCP security risks. The server’s lockdown mode (X-MCP-Lockdown: true on the hosted server) hides public issue and pull request content from authors without push access. GitHub is clear that it is a best-effort filter, not an authorisation boundary.

The local server and browser sign-in

If you would rather sign in through the browser than hold a token, run the server locally. GitHub’s official image includes its own app credentials, opens a browser login on first use and keeps the token in memory only. The Docker form publishes a fixed callback port on loopback:

claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- \
  docker run -i --rm -p 127.0.0.1:8085:8085 \
  -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server

The local server takes --toolsets, --read-only and --lockdown-mode, or the matching GITHUB_TOOLSETS, GITHUB_READ_ONLY and GITHUB_LOCKDOWN_MODE environment variables. It is also the route for GitHub Enterprise Server, which cannot use the hosted server; GitHub Enterprise Cloud with data residency has its own hosted address on its ghe.com domain.

Claude on the web and desktop

GitHub’s guide says the hosted server cannot currently be added to Claude Desktop as a custom connector, because it needs OAuth through a GitHub App or OAuth App registered for that client. It recommends the local Docker server in Claude Desktop’s configuration file instead, and notes that some people have had trouble with Docker-based servers there.

Limits to know

• Rate limits. Calls are subject to GitHub’s API rate limits for the credential you use.
• It works as you. A personal token has no separate identity; on a shared repository your team sees your name on the assistant’s changes.
• Large results fill context. Claude Code warns when one MCP result passes 10,000 tokens and caps output at 25,000 by default. Ask for one repository, label or project at a time.
• More toolsets, more tools. Turning on all is easy and makes tool choice harder; add toolsets as you need them.

Removing it

claude mcp remove github

Then revoke the token in your GitHub settings. Removing the server only deletes the local entry; the token keeps working until it is revoked or expires.

If the people on the work are not all on GitHub

GitHub Projects is the natural board when everyone has a GitHub account and the work is issues and pull requests. When the work also involves a client, a designer or a tester, fenbs is a board they can join with an email and a role, and Claude Code can be a member of it with its own role, its changes recorded in the board’s history. A common shape is to keep pull requests on GitHub and features, enhancements and bugs on fenbs, with the issue number in each task’s reference field, and let an assistant connected to both keep them in step. The fair comparison is on fenbs vs GitHub Projects, and the setup is on the Claude Code page.