GitHub MCP — Use Cases, Install & Live Demo

Name: GitHub MCP Server
Author: github

Why use it

Key features

First-party — published and signed by GitHub
Read-only mode for safe exploration; explicit opt-in for write tools
Fine-grained PAT support — scope to specific repos and permission sets
Includes code search via the GitHub Search API
Distributed as a signed Docker image, no npm install of unverified code

Live Demo

What it looks like in practice

github.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "github",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "github": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use GitHub

How to find a good first issue and ship a fix in an hour

👤 Open-source contributors looking for a low-friction first PR ⏱ ~60 min beginner

When to use: You want to contribute to a project but have no idea where to start. The maintainer's CONTRIBUTING.md is too generic to be useful.

Prerequisites

GitHub PAT with repo:read and issues:read — github.com/settings/tokens — fine-grained, scoped to the repo you want to contribute to
filesystem MCP installed too — lets Claude clone and read the repo locally to actually write the fix

Flow

Ask Claude to find issues marked good first issue with no comments, sorted by simplicity

Find open issues in modelcontextprotocol/servers labeled 'good first issue' with no assignee and zero comments. Pick the one that looks easiest to fix and explain why.✓ Copied

→ Claude returns 3-5 candidates with a one-line difficulty assessment for each
Have Claude fetch the issue body and any linked code

Pull the full issue body for #<num> and read the file it mentions. Tell me the actual change that needs to happen.✓ Copied

→ Concrete diff intent, not just a restatement of the issue
Use filesystem MCP to make the edit, then GitHub MCP to draft the PR

Apply the change, write a PR description that thanks the maintainer and explains the fix in 3 sentences.✓ Copied

→ PR opens with link returned

Outcome: An open PR that respects the project's style, references the issue, and is small enough to merge same-day.

Pitfalls

Claude picks a 'good first issue' that's actually been festering for 2 years because nobody could agree on the fix — Add not in last 90 days have new comments from maintainers as a filter
PR body is generic AI-speak — Tell Claude to mimic the tone of the project's last 3 merged PRs first

Combine with: filesystem · git

Generate a weekly PR digest for your team

👤 Engineering managers, tech leads ⏱ ~10 min intermediate

When to use: Every Monday morning when you'd rather not click through 40 PR notifications.

Prerequisites

PAT scoped to your team's repos with pull_requests:read — Use a fine-grained token, never a classic 'all repos' token

Flow

Ask for last week's merged PRs with their diff sizes

List all PRs merged into our org/repo between last Monday and today. Include author, +/- lines, and one-line summary.✓ Copied

→ 10-30 row table with concrete deltas
Group by author and theme

Group these by area (auth, payments, frontend, infra...) and flag any that look like reverts or hotfixes.✓ Copied

→ Sections with thematic clustering
Draft a Slack-ready digest

Now write a Slack post summarizing the week — celebrate the big wins, call out the risky changes, name the people who shipped them.✓ Copied

→ Markdown with @mentions, emoji, ready to paste

Outcome: A 5-bullet summary you actually want to read on Monday morning.

Pitfalls

Hits the rate limit if your org has many repos — Filter to one repo at a time, or upgrade to a GitHub App token (15k req/h vs 5k)

Combine with: linear · sentry

Find every place your codebase uses a deprecated API

👤 Backend engineers planning a migration ⏱ ~30 min intermediate

When to use: You're about to deprecate an internal class/function and need to know who's using it before you announce.

Prerequisites

PAT with repo:read for all repos in your org — Use a GitHub App for org-wide access — easier than juggling per-repo PATs

Flow

Use code search across the org

Search across our entire acme-corp org for any usage of the LegacyAuth class. Return file paths grouped by repo.✓ Copied

→ List of repos and files, with line numbers
For each match, fetch context

For each match, fetch 5 lines around the usage and tell me whether it's a real call or just a comment/import.✓ Copied

→ Filtered list distinguishing real calls from noise
Generate a migration tracking issue

Create a tracking issue in acme-corp/platform titled 'Migrate off LegacyAuth' with a checklist of every real callsite and the team that owns each repo.✓ Copied

→ Issue created with comprehensive checklist

Outcome: A single source-of-truth tracking issue your platform team can use to drive the migration.

Pitfalls

Code search has a 1000-result cap per query — If you hit it, narrow by language or path: LegacyAuth language:python or split queries by repo prefix
GitHub indexes only the default branch — Won't find usage in feature branches — supplement with a local grep on cloned repos

Combine with: filesystem

Get a second opinion on a tricky PR before approving

👤 Code reviewers facing a PR outside their expertise area ⏱ ~15 min intermediate

When to use: You're the assigned reviewer on a PR that touches code you don't know well, and you don't want to just rubber-stamp.

Flow

Pull the PR diff and description

Fetch PR #<num> in org/repo — give me the diff and the description. What's the author claiming this does?✓ Copied

→ Clear restatement of intent
Ask for an architectural read

Now look at the existing files this PR touches. Does the change fit the existing patterns, or does it introduce a new one? If new, is the new pattern justified?✓ Copied

→ Specific call-outs, not generic praise
Probe for risks

Where in this diff is something most likely to break in production 6 months from now? Be specific — point to the line.✓ Copied

→ Concrete line-level concerns, not 'add more tests'

Outcome: Three specific, actionable comments you can post on the PR — making your review meaningfully better than a glance.

Pitfalls

Claude becomes a yes-machine and praises everything — Explicitly ask 'what would a senior engineer at this company push back on?' — adversarial framing helps

Combine with: filesystem

Identify and unstick PRs rotting in review

👤 Engineering leads, repo maintainers ⏱ ~20 min beginner

When to use: Once a sprint, when you suspect PRs are quietly aging out without anyone noticing.

Flow

List PRs open for >5 days with no recent activity

Find open PRs in org/repo last updated more than 5 days ago. For each, tell me the author, the assigned reviewer, and the stated reason for delay (look at the last comment).✓ Copied

→ Table with diagnosis per PR
Categorize the delay

Group these into: 'waiting on reviewer', 'waiting on author', 'waiting on CI', 'waiting on decision'. Be specific about which.✓ Copied

→ 4 categories with concrete PRs in each
Draft nudges

For the 'waiting on reviewer' bucket, draft a polite nudge comment for each. Different tone if the reviewer is a peer vs senior to the author.✓ Copied

→ Per-PR comment text ready to paste

Outcome: A short list of PRs you can unblock in 15 minutes, with specific actions per PR.

Pitfalls

Auto-posting comments feels spammy — Have Claude draft the comments but you post them yourself — keeps the human-in-the-loop

Combine with: linear

Combinations

Pair with other MCPs for X10 leverage

github + sentry

Sentry surfaces a new error → GitHub MCP finds the commit that introduced it via release tags → you draft a hotfix PR, all in one chat

There's a new error in Sentry — issue WEB-3a91. Find which commit on main introduced it (cross-reference the release tag), then draft the smallest possible revert PR.✓ Copied

github + linear

Auto-create Linear issues from GitHub bug reports with proper labels and priority

For every issue opened in our octocat/api repo this week with label 'bug', create a matching Linear issue in the BACKEND team with priority Medium.✓ Copied

github + filesystem + git

End-to-end contribution: clone repo locally, make changes, push branch, open PR — without leaving the chat

Clone acme/widgets locally, fix the typo in src/utils/format.ts:42, push to a new branch, open a PR.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
search_issues	owner: str, repo: str, labels?: str[], state?: str	You want to find issues by label, state, assignee, or activity	1 GitHub API call
get_issue	owner: str, repo: str, issue_number: int	After search_issues, when you need the full conversation	1 API call
create_issue	owner, repo, title, body, labels?, assignees?	File a new issue — make sure the user actually wants this	1 API call (write)
list_pull_requests	owner, repo, state?, sort?, base?, head?	Find PRs by state/branch/author	1 API call
get_pull_request	owner, repo, pull_number	Read a specific PR's diff and metadata	1 API call
merge_pull_request	owner, repo, pull_number, merge_method?	Only when explicitly told — use dry-run discussion first	1 API call (write, irreversible)
search_code	q: str, sort?	Find symbol usage across an org	1 API call (lower rate limit: 30/min)
get_file_contents	owner, repo, path, ref?	Read a single file from a repo without cloning	1 API call
create_or_update_file	owner, repo, path, message, content, sha?	One-off file edit; for multi-file changes use a branch + PR	1 API call (write)
list_commits	owner, repo, sha?, path?	Audit history of a file or branch	1 API call

Cost & Limits

What this costs to run

API quota: Personal PAT: 5,000 requests/hour. GitHub App: 15,000/h. Code search: 30/min on personal, separate.
Tokens per call: 200–500 tokens for issue/PR metadata; can balloon to 5k+ for large file fetches
Monetary: Free with any GitHub account. GitHub Enterprise has higher limits.
Tip: If you're hitting limits, switch to a GitHub App — easier than juggling multiple PATs and gives 3× the rate. Cache list_issues results when iterating.

Security

Permissions, secrets, blast radius

Minimum scopes: repo:read issues:read

Credential storage: Fine-grained PAT in environment variable (e.g. GITHUB_PERSONAL_ACCESS_TOKEN). Never commit to dotfiles.

Data egress: All API calls to api.github.com only. No third-party telemetry.

Never grant: admin:org delete_repo admin:enterprise

Use a fine-grained PAT scoped to specific repos, not a classic 'all repos' token.
Disable write tools (issues:write, pulls:write) until you trust your prompts.

Troubleshooting

Common errors and fixes

401 Unauthorized

Your PAT expired or doesn't have access to that repo. Re-create at github.com/settings/tokens with the right scopes.

Verify: curl -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" https://api.github.com/user

403 rate limit exceeded

You've hit 5000 req/h on a personal PAT. Wait until the reset window, or migrate to a GitHub App token (15k/h).

Verify: curl -H "Authorization: Bearer $TOKEN" https://api.github.com/rate_limit

404 Not Found on a private repo

PAT doesn't include that repo in its allowed-repos list. Edit the fine-grained PAT and add the repo.

Docker: 'unable to find image'

Pull the image first: docker pull ghcr.io/github/github-mcp-server. Check you're authenticated to ghcr.io if it's private.

Verify: docker images | grep github-mcp-server

Alternatives

GitHub vs others

Alternative	When to use it instead	Tradeoff
GitLab MCP	You use GitLab.com or self-hosted GitLab instead of GitHub	Smaller feature surface, community-maintained
Gitea MCP	Self-hosted Gitea installation	Limited tooling vs the official GitHub MCP
git MCP	Just need local git operations (status, log, diff, blame) without any remote	No issues, PRs, or remote operations — works on any local repo without auth

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills