Setup GitHub MCP Server with Cursor or Claude Code

If GitHub should be the first MCP server in your stack, most failed installs do not come from GitHub itself.

They come from mixing three decisions together:

which host should own the first run
whether hosted HTTP or local Docker is the right transport
whether the first test is proving context access or trying to do real coding

Split those apart and the setup gets much easier.

Start By Choosing Which Host Owns The First Run

Treat this as two different setup paths that happen to point at the same GitHub MCP server.

Pick Cursor when the work already lives in the editor and you want GitHub context next to file navigation, in-editor review, and agent turns.

Pick Claude Code when the work already lives in the terminal and you want the repo directory, CLI scope, and MCP registration flow to stay explicit.

Do not set up both hosts first just because you might compare them later.

If the install fails, you will not know whether the problem came from GitHub auth, HTTP transport, Docker, JSON config, or the client itself.

Shared Prep Before You Touch Any Host Config

Before touching any settings, decide four things:

Which repository and which issue or PR you will use for the first proof run.
Whether the hosted GitHub endpoint should be the first route.
Whether the config is personal-only or should be shared with a project.
Whether the first success condition is simply "can read repo context correctly?"

The common pieces are straightforward:

the hosted endpoint is https://api.githubcopilot.com/mcp/
the supported local server is the Docker image ghcr.io/github/github-mcp-server
the retired npm package @modelcontextprotocol/server-github should not be part of a new setup

One practical rule matters more than people expect:

If the first proof run uses a private repository, check the PAT before you touch anything else. GitHub's own troubleshooting guidance still points back to token scope when private repos do not show up.

This is the shortest safe sequence: prepare GitHub once, wire one host, verify the server, and prove one repo-reading task before asking for code edits.

Three Setup Mistakes That Make The Install Look Broken

Setting Up Both Hosts Before One Path Is Stable

This doubles the uncertainty without doubling the learning.

Get one host reading GitHub first. Compare hosts later.

Jumping Straight To Code Generation

If the host cannot read one issue, see one repository, and name believable files, asking it to write code only hides the real problem.

Treating Docker As The Default Instead Of The Fallback

For most builders, hosted HTTP is the shorter route when the host supports it. Docker is the fallback when the hosted endpoint is blocked or you explicitly want the GitHub MCP process to stay local.

Cursor Is Shorter When The Editor Already Owns The Workflow

Cursor is the cleaner first route when the evaluation happens inside the IDE.

The configuration is file-based, which makes it easy to inspect but also easy to leak if you hardcode a PAT into a project file that should never be committed.

The practical split is still:

~/.cursor/mcp.json for personal setup across projects
.cursor/mcp.json for project-specific setup

Cursor's MCP docs also still support interpolation in command, args, env, url, and headers, which means you can point at ${env:GITHUB_PAT} instead of pasting a raw token.

Use The Hosted GitHub Endpoint First In Cursor

GitHub's current Cursor guide still recommends the hosted server first and notes that Streamable HTTP requires Cursor v0.48.0 or newer.

If you want the shortest route, set GITHUB_PAT in your shell or system environment and use:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_PAT}"
      }
    }
  }
}

GitHub's own example still shows a literal PAT in the JSON. That is fine for a personal config if you accept the tradeoff. It is the wrong default for a project file.

Use Docker In Cursor Only If Hosted HTTP Is Actually Blocked

If corporate proxy rules or connection failures make hosted HTTP non-viable, then switch to the local Docker server:

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

This is slower because Docker becomes part of the troubleshooting path. Use it because the network path failed, not because "local" feels more robust.

Verify Cursor Before You Ask For Anything Real

GitHub's current verification loop is still simple:

Restart Cursor fully.
Open Settings -> Tools & Integrations -> MCP Tools.
Confirm the github server shows a green status dot.
Check that GitHub tools appear under Available Tools.
Ask the smallest possible question: List my GitHub repositories.

If the green dot never appears, stop there. The usual causes are invalid JSON, an unset GITHUB_PAT, a host version that is too old for hosted HTTP, or Docker not running for the local route.

Claude Code Is Cleaner When The Terminal Should Define Scope

Claude Code is the better first host when the workflow should stay terminal-native and the project directory itself should define what is in scope.

Anthropic's MCP docs still make two practical things clear:

HTTP is the recommended transport for remote servers
scope matters: local by default, plus project and user when you want shared or cross-project visibility

That means the setup question is not only "which command works?" It is also "where should this server live?"

Use The Current GitHub-Specific Command First

There is one wrinkle here.

Anthropic's general Claude Code docs now show claude mcp add --transport http ... as the basic HTTP pattern. But GitHub's own Claude Applications install guide still documents a GitHub-specific claude mcp add-json route for Claude Code 2.1.1+, and keeps the older claude mcp add --transport http ... form as the fallback for older versions and Windows parsing trouble.

For the current GitHub route, start with:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

If you want it available across projects, add a scope:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}' --scope user

If the token is personal and the setup is just for you, local or user is usually the right first choice. Use project only when the team truly wants a shared .mcp.json file.

Use The Older HTTP Form As The Real Fallback

GitHub's guide explicitly calls out a Windows edge case: claude mcp add-json may return Invalid input when adding an HTTP server.

If that happens, or if you are on Claude Code 2.1.0 or earlier, switch immediately to the older command format:

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

For native Windows PowerShell, GitHub's guide gives this variation:

$pat = "YOUR_GITHUB_PAT"
claude mcp add github --transport http https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer $pat"

That looks like a tiny difference. It is often the difference between a working install and ten minutes lost to parser errors.

Use Docker In Claude Code Only When Hosted HTTP Is Not The Right Route

If hosted HTTP is blocked or you explicitly want the local server, GitHub still documents the Docker route:

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-server

GitHub also documents a binary-based local route if Docker is not available. That is useful, but it is not the first thing to reach for when the real goal is simply to get the first GitHub workflow running.

Verify Claude Code From The CLI And From `/mcp`

After setup:

claude mcp list
claude mcp get github

Then inspect status inside Claude Code with:

/mcp

If the server is missing, check the boring things first:

you added it in the scope you are actually testing
the PAT still has the repo access you need
Docker is running if you chose the local route
you are not mixing the wrong command format with the wrong Claude Code version or Windows shell behavior

Use One Boring Prompt To Prove The Install

Once the server looks healthy, do not benchmark it. Prove it.

Use this:

Use GitHub MCP tools only for context gathering.

1. Confirm that you can access this repository: [owner/repo]
2. Read this issue or pull request: [link or number]
3. Name the files most likely involved and explain why
4. Summarize the smallest next implementation step in 5 bullets or fewer
5. Stop before editing code if repo access, issue context, or permissions look incomplete

This prompt is deliberately boring. That is the point.

If the host can access the repo, read the issue, and suggest believable files, the install is already useful. If it cannot, adding more MCP servers will only blur the real failure.

What A Successful First Run Actually Looks Like

The first success condition is smaller than people expect:

the host can see the repository
the issue or PR is readable
the file shortlist is believable
the next step is small enough that a developer would trust it

That is enough. You do not need code edits on the first run to know the setup works.

What Usually Breaks The First Install

Most failed first runs still come from one of these mistakes:

following an older tutorial that still points at @modelcontextprotocol/server-github
storing config in the wrong scope or wrong file location
hardcoding a PAT into a shared config and then refusing to commit it, leaving everyone else with a broken file
using a PAT that cannot see the private repo you picked for the first proof run
switching to Docker before checking whether hosted HTTP already works
trying to prove both Cursor and Claude Code before one route is stable

The fix is usually subtraction, not more tooling.

Which Host To Keep After GitHub Works

Once GitHub MCP is stable, the host decision gets simpler.

Keep Cursor if:

you want GitHub context and file edits in one editor surface
you care about fast file hopping and inline agent turns
review already happens naturally from the IDE

Keep Claude Code if:

you want the working directory to define scope clearly
you prefer explicit CLI control over server registration and scope
GitHub MCP should be one tool inside a terminal-first execution loop

The better host is not the one with the better demo. It is the one that makes repo context easier to use in the place where you already work.

Official References

What To Read Next

Read How To Choose An MCP Server For GitHub Workflows if GitHub is now working and the next question is whether you actually need another connector.

Read Common MCP Server Setup Mistakes if the problem still feels lower-level than host choice.

Read Use GitHub MCP with Claude Code to Review a Pull Request Before Merging if setup is stable and you want a safer first workflow than code generation.

Read Cursor vs Claude Code if GitHub now works and the only unresolved question is which host should keep the workflow.