Connecting Claude to GitHub: repos, issues, and prs

Where each one lives

| Surface | How GitHub access works |

|---|---|

| Claude web / desktop / mobile | GitHub connector (OAuth) |

| Claude Code (terminal) | GitHub MCP server, or the gh CLI it can shell out to |

| Anthropic APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → / Agent SDK | You attach the MCP server in your tool config |

Setting up the MCP server in Claude code

Claude Code is the terminal agent that already operates on your local checkout. Adding the GitHub MCP server lets it cross from your local files into the remote: issues, PRs, Actions runs, reviews.

The cleanest setup uses the remote GitHub MCP server with OAuth. From your repo:

On first use Claude Code triggers a browser OAuth flow. Confirm the connection any time with:

If you prefer a tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → instead of OAuth (common in CI), set a fine-grained personal access tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → as an environment variable and pass it through. We'll cover exactly which permissions that tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → needs next, because this is where most people over-grant.

TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → permissions: grant the least you need

This is the part to get right. A GitHub tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → that can read and write *everything* is a liability, especially when an autonomous agent is the one holding it.

GitHub offers fine-grained personal access tokens that scope to specific repositories and specific permission categories. For a Claude workflow that reads a repo, triages issues, and opens PRs, you want:

• Contents: Read and write (read source files, create branches, push commits)
• Pull requests: Read and write (open and update PRs)
• Issues: Read and write (triage, comment, label)
• Metadata: Read (required baseline; GitHub auto-selects it)

That's it. You do not need admin, you do not need workflow write unless Claude is editing files under .github/workflows/, and you should scope the tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → to the single repo you're working in, not your whole account.

Create one at GitHub → Settings → Developer settings → Fine-grained tokens, select the target repo, set the four permissions above, and give it a short expiry. Then:

A key mental model: the connector's OAuth flow and your fine-grained tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → are the *ceiling* on what Claude can do. The model cannot exceed those scopes no matter how it's prompted. Permissions are your real safety control, not the prompt.

The concrete workflow: summarize a repo, then open a PR

Here's the end-to-end example the hook promised. Assume you're in Claude Code inside a checked-out repo with the GitHub MCP server connected.

Step 1: Summarize the repository

You don't need a clever prompt. Be specific about what "summary" means to you:

> Read this repo's structure, README, and main entry points. Give me a one-paragraph summary of what it does, the primary tech stack, and the three areas most likely to contain bugs. Then list the open issues labeled bug, sorted by how actionable they look.

Claude uses the MCP tools to list files, read the README and package manifest, and call the issues endpoint. Because Claude Code also has your local files, it reads source directly and uses the MCP server mainly for the *remote* state (issues, PR list, CI status). The output is a grounded summary, not a guess, because it actually pulled the content into context.

Step 2: Pick a fix and draft it

Say one issue reads: *"parse_date throws on empty string instead of returning None."* Tell Claude:

> Reproduce issue #42 with a quick test, fix parse_date so an empty or whitespace-only string returns None, and make sure existing tests still pass.

Claude locates the function, writes the fix, runs your test suite locally, and iterates if something fails. This is the part that the connector-in-the-app version handles less well, because it can't *run* your tests. Claude Code can.

Step 3: Open the pull request

Now the GitHub-specific step. Claude creates a branch, commits, pushes, and opens a PR through the MCP server's pull-request tool:

> Create a branch fix/parse-date-empty, commit the change with a clear message, push it, and open a PR against main. Reference issue #42 in the description and explain the fix in two sentences.

Behind the scenes that maps to GitHub APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → calls the tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → authorized: create-ref, create-commit, and create-pull-request. You get a real PR URL back. Nothing merges automatically. You review, your CI runs, and a human approves.

If you wanted this fully scripted instead of conversational, the same capability is available through the Claude Agent SDK, where you attach the MCP server as a tool and let a managed agent run the loop. A minimal tool attachment looks like:

Notice allowed_tools: even with the server connected, you allowlist exactly which GitHub tools the agent may call. That's a second layer of control on top of the tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → scope. See the Claude Agent SDK docs for the full tool APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →.

Triage at scale: issues as a feed

Opening PRs is the dramatic demo, but the quieter daily win is issue triage. With read/write on issues, Claude can:

• Label incoming issues by area and severity using your existing label taxonomy
• Detect duplicates by comparing a new issue against open ones
• Draft a first-response comment asking for a repro when one's missing
• Summarize a noisy 40-comment thread into a decision and next action

A pattern that works well: keep this in a Project in the Claude app with the GitHub connector attached and a Style that enforces your team's tone for issue comments. The Project holds the standing context (your label definitions, your triage rules); the connector supplies live issue data; the Style keeps Claude's public comments consistent. You're combining three Claude features you already know into one repeatable workflow.

For high-volume repos, push triage into CI: a GitHub Action runs Claude Code on each new issue with a tightly scoped tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → and a fixed prompt. The tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → still caps what it can touch, so a misfire labels an issue wrong at worst, it can't push code.

What the connector can't do, and why that's good

The consumer GitHub connector deliberately can't execute arbitrary code, can't run your test suite, and can't reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → private infrastructure. If you ask the app to "fix and verify," it can read and propose, but verification needs Claude Code or your CI.

This boundary is a feature. The app connector is for reading, reasoning, and drafting. The moment you need execution, you've crossed into Claude Code or the Agent SDK, where you've explicitly granted a tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → and allowlisted tools. The capability escalates only as deliberately as you let it.

A few guardrails worth standardizing on your team:

• Branch protection on `main` so no agent-opened PR can merge without review and green CI.
• Short token expiry and per-repo scoping, rotated regularly.
• Tool allowlists in any SDK or agent config, never "all tools."
• Review every PR. Claude drafts; humans merge. Treat agent PRs exactly like a new contributor's first PR.

Key Takeaways

• Pick the right path: the GitHub connector in the Claude apps for reading and triage, the GitHub MCP server in Claude Code or the Agent SDK when you need to run tests and push real PRs.
• Scope a fine-grained token to four permissions: Contents, Pull requests, and Issues (read/write) plus Metadata (read), limited to one repo with a short expiry. Permissions, not prompts, are your safety control.
• The summarize-then-fix loop is concrete: read the repo and issues, reproduce and fix locally with Claude Code, then create branch → commit → push → PR through the MCP pull-request tool. Nothing merges without you.
• Layer your controls: tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → scope caps capability, allowed_tools allowlists specific actions, and branch protection guarantees human review before merge.
• Combine features you already have: a Project for standing triage rules, a Style for comment tone, and the connector for live data turns ad-hoc help into a repeatable team workflow.