GitHub MCP in Claude Code

Quick answer: Install the GitHub MCP server with npx -y @modelcontextprotocol/server-github, add the JSON block below to ~/.claude/settings.json, restart Claude Code, and run /mcp to confirm the connection. Setup runs about 5 minutes on a fresh machine, verified on @modelcontextprotocol/server-github as of April 15, 2026.

The GitHub MCP server wraps the REST and GraphQL APIs into a tool surface Claude Code can call directly. After setup, the model can open issues, create branches, push commits, read diffs, approve pull requests, and search across an entire organization without you switching away from the editor. The server is published by Anthropic as @modelcontextprotocol/server-github and uses a personal access token for auth.

This guide covers what you get after the wiring is done, the exact config, verification steps, prompt patterns that tend to work well, and the 4 issues that trip people up most often in the first week.

What you get when it is connected

Once the GitHub server is attached, Claude Code can call the server tools from inside any conversation. You do not invoke the tools by hand. When you ask Claude a question the model decides which tool to call and parses the response for you. For teams that live inside GitHub day to day, this replaces dozens of context switches per week with a single line in chat.

The server exposes roughly 25 tools across issues, pull requests, repository contents, search, and users. Reads return structured JSON the model parses directly; writes return the new resource so Claude can link back to it in chat. There is no local cache. Every call round-trips to GitHub, so expect 200 to 600 ms per tool call depending on region and payload size.

Prerequisites

A GitHub account, Node 20 or later, and a fine-grained personal access token scoped to the repositories you want Claude to reach. Classic tokens work too but fine-grained is the recommended path for 2026 since it lets you cap permissions per repo.

If you use a version manager like nvm or asdf for Node, confirm the version Claude Code inherits. Open a terminal, run node -v, and note the output. Claude Code uses the Node it sees on PATH at launch, so a shell profile that sets the right version is the reliable path.

Install via npx

Run the package once with npx to verify it starts cleanly:

npx -y @modelcontextprotocol/server-github

The first run downloads the package (a few MB) and starts the server on stdio. The server does not print much on success - it waits for MCP protocol messages on stdin. Press Ctrl-C to stop it. The actual runtime setup happens through Claude Code itself in the next step.

If the install fails with a network error, your npm registry may be blocked. Set npm config set registry https://registry.npmjs.org and retry. Behind a corporate proxy, also set HTTP_PROXY and HTTPS_PROXY in your shell.

Add the config block to ~/.claude/settings.json

Open ~/.claude/settings.json in your editor. If the file does not exist yet, create it with {} as the starting content. Add an mcpServers object with an entry for this server:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_XXX"
      }
    }
  }
}

Save the file. If you already have other MCP servers defined, merge the new entry into the existing mcpServers object rather than replacing it.

Restart Claude Code fully (quit and reopen, not just close the window). The server is spawned lazily on the first tool call in a session, not at launch, but the config is read once per Claude Code start.

Verify the connection

Open a new Claude Code session and type /mcp at the prompt. You should see the server listed with a green or connected indicator. If it shows as failed, click into it for the stderr output - the error message usually points at the problem directly (bad token, wrong path, missing Node).

Run a trivial first prompt to confirm round trips work. Good smoke tests:

• For read servers: ask for a list of whatever resource type it exposes.
• For write servers: ask for a describe on a known resource first, then try a safe write on a test resource.

If the first prompt works, the wiring is done. From here on you interact with the server purely through normal prompts in Claude Code.

Example prompts that work well

Here are prompts that tend to get good responses once the server is attached:

• Create a new issue in the anthropics/claude-code repo titled "Add JSON output to /mcp" with the label enhancement and assign it to me.
• Open a pull request from the fix/rate-limit branch into main with a summary of the three commits and request review from @octocat.
• List every open issue in my-org/api-service tagged bug, sorted by most recently updated, and show who filed each one.
• Read the diff for PR #432 in my-org/web, summarize the user-facing changes, and post a review comment asking about the cache invalidation path.
• Search the anthropics org for any file that imports deprecated_api and give me the file paths with line numbers.
• Create a release in my-org/cli tagged v2.3.0 with release notes generated from the commits since v2.2.0.

Claude will chain tool calls on its own when the prompt implies several steps. For a summarize-then-write flow the model will often call read tools first, then a single write tool at the end. If a prompt keeps burning tool calls, narrow it: specify the resource ID, the time range, or the exact field you want rather than asking Claude to scan everything.

Environment variable security

The token lives in GITHUB_PERSONAL_ACCESS_TOKEN. Generate it at github.com/settings/personal-access-tokens with read-and-write access on contents, issues, and pull requests for the specific repos you want Claude to touch. Never commit the token. Store it in a shell profile env var and reference the variable name in the Claude config, or use a secrets helper like op read if you run 1Password CLI.

A general rule across every MCP server: never paste secrets directly into settings.json that lives in a shared or git-tracked directory. Keep the actual secret values in your shell profile (~/.zshrc, ~/.bashrc, or a 1Password-cli helper), export them at shell start, and reference the variable names from the Claude config. That way the secret stays on your machine and the config file is safe to share with teammates.

On macOS, terminals launched from Spotlight or from the Dock both inherit the shell profile. If you launch Claude Code from a GUI shortcut that does not go through a shell, env vars may not propagate - launch from a terminal instead.

Troubleshooting

Tool calls return 401 Bad credentials. The token is wrong, expired, or scoped to the wrong account. Regenerate at github.com/settings/personal-access-tokens, paste the new value into your config, and restart Claude Code.

Tool calls return 403 Resource not accessible. The token scope is missing the permission the call needs. Fine-grained tokens need explicit opt-in per repo for write endpoints. Edit the token and toggle on pull_requests:write and contents:write.

Rate limit hit after a few searches. Unauthenticated search caps at 10 requests per minute. Verify the token is actually attached by running /mcp in Claude Code; the server should show github connected. If not, the env var did not propagate.

GraphQL calls fail but REST works. GraphQL needs the same token but hits a different endpoint. Corporate firewalls sometimes block api.github.com/graphql specifically. Try from a direct network or whitelist the endpoint with your network team.

For any issue not listed here, the first step is /mcp inside Claude Code to see the current status and any recent stderr from the server. The second step is running the exact npx command from your terminal to see if the server starts cleanly outside Claude Code. Between those two checks, most problems become obvious within a minute.

Next steps

Once the GitHub server is attached and verified, the useful next move is writing a short prompt template you keep in your notes. List the 3 or 4 prompts you run most often against this server, and paste them into Claude Code when needed. Over a few weeks you build a personal command library that gets real work done without typing much.

For team projects, commit a .mcp.json at the repo root with the same structure. Everyone on the team gets the server wired up automatically on first open, and individual secrets stay in shell profiles. That is the setup pattern that scales past a single developer.