GitHub MCP Server Setup: Toolsets and Read-Only
On this page
What it gives your agent
With the GitHub MCP server connected, you can ask "summarize the open issues labeled bug", "open a PR from this branch with a description" or "why did the last CI run fail?" and the agent does it through GitHub's API. It's the server that shows up first on almost every "best MCP servers" list, and it's maintained by GitHub.
You have two ways to run it:
| Option | URL or command | Good for |
|---|---|---|
| Hosted (remote) | https://api.githubcopilot.com/mcp/ | Most people. Nothing to install |
| Local (Docker) | ghcr.io/github/github-mcp-server | GitHub Enterprise Server, or when you want it on your own machine |
Step 1: create a token
Most clients connect with a personal access token (PAT). VS Code can sign in with OAuth instead, but Cursor and Claude Code use a token. Create a fine-grained token in GitHub under Settings, Developer settings, Personal access tokens, and give it access to only the repositories you'll use.
Grant the smallest permissions that cover your tasks. For reading code and issues, read access is enough. Add write access to issues or pull requests only if you want the agent to create them. Then put the token in an environment variable so it stays out of config files:
export GITHUB_PAT=github_pat_your_token_hereStep 2: add it to your tool
Claude Code. GitHub's install guide uses add-json for current versions:
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'To share it with your team, put it in the project's .mcp.json with ${GITHUB_PAT} in place of the token. Claude Code expands it from each person's environment.
Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${env:GITHUB_PAT}" }
}
}
}VS Code (.vscode/mcp.json). VS Code can use OAuth, so no token is needed. It opens a GitHub sign-in the first time:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/"
}
}
}Codex CLI reads the token from the variable at runtime:
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PATGemini CLI:
gemini mcp add -s user -t http github https://api.githubcopilot.com/mcp/ -H 'Authorization: Bearer $GITHUB_PAT'Step 3: give it only the tools you need
The server has dozens of tools grouped into toolsets, such as repos, issues, pull_requests, actions, code_security, discussions and notifications. Loading all of them costs tokens on every request and gives the agent more ways to do something you didn't intend. Two controls help.
Pick toolsets. On the hosted server, add one toolset to the URL path, such as https://api.githubcopilot.com/mcp/x/repos. For several, send a header instead:
"headers": {
"Authorization": "Bearer ${env:GITHUB_PAT}",
"X-MCP-Toolsets": "repos,issues,pull_requests"
}Make it read-only. Add /readonly to the URL (https://api.githubcopilot.com/mcp/readonly) or send X-MCP-Readonly: true. Write tools are then skipped entirely. This is a good default for exploring a codebase or triaging issues.
Running it locally with Docker
The local server takes the same token as an environment variable. In Claude Code:
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT \
-- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-serverLocally, choose toolsets with the GITHUB_TOOLSETS environment variable (for example repos,issues) and turn on read-only mode with GITHUB_READ_ONLY. For GitHub Enterprise Server, set GITHUB_HOST to your server's https:// address. Enterprise Server can't use the hosted endpoint, so the local server is your option there.
Check it works
Ask: "List the five most recent open issues in owner/repo." You should see a call to an issues tool and a short list. If you get a 401 error, the token is missing or expired. If you get a 404 on a private repository, the token doesn't have access to that repository.
Check yourself
Use https://api.githubcopilot.com/mcp/readonly, or send the X-MCP-Readonly: true header. Write tools are skipped.
The local server, with GITHUB_HOST set to your server's https:// address. Enterprise Server doesn't support the hosted endpoint.
Every tool's definition is sent with each request. Fewer tools means fewer tokens and less chance of the agent picking the wrong one.