Setup GitHub MCP Server with Cursor or Claude Code

If you already decided that GitHub should be the first MCP server in your stack, the next failure point is usually not GitHub itself. It is the host-side setup. Cursor and Claude Code both support the GitHub MCP server now, but the setup surfaces are not identical, and older blog posts still send people toward the retired @modelcontextprotocol/server-github package.

This page keeps the job narrow. Do the GitHub prep once, pick the host you actually use, prove one repo-context task, and stop there. That gets you a live signal much faster than wiring multiple MCP servers before the first one can even read an issue correctly.

Fast Answer

Use GitHub's hosted MCP endpoint first if your host supports it. It is the shortest setup path.
Use Cursor if the work mostly stays in the editor and review happens file-by-file.
Use Claude Code if the work mostly stays in the terminal and inside one repo root.
Keep the local Docker server as the fallback when hosted HTTP is blocked or you want the MCP process under local control.
Do not follow older tutorials that still install @modelcontextprotocol/server-github. GitHub deprecated that package in April 2025.
The first success condition is simple: the agent can read one repository plus one issue or PR without inventing context.

Decide 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 your workflow already lives in the editor: you want the GitHub context to appear next to code review, file navigation, and in-editor agent turns.

Pick Claude Code when your workflow already lives in the terminal: you want to open one repo, keep the scope obvious, and manage the MCP server from the CLI.

Do not configure both hosts as the first move just because you might compare them later. If the setup fails, you will not know whether the breakage came from GitHub auth, the server transport, or the client.

If you are still undecided, read Cursor vs Claude Code after this tutorial. The setup work here is easier if you already know which surface you plan to keep.

Start With One Shared Checklist

Before touching any host config, do these four things:

Create one GitHub Personal Access Token for the repos and actions you expect the agent to touch.
Decide whether you want GitHub's hosted endpoint or the local Docker image.
Choose whether the configuration should live only for you or be shared with a project.
Pick one real repository and one real issue or PR for the first proof run.

GitHub's current install guides split Cursor and Claude into separate pages for a reason. The GitHub server is the same, but the client rules are different:

Cursor uses mcp.json files and can load either a global file at ~/.cursor/mcp.json or a project file at .cursor/mcp.json.
Claude Code uses claude mcp commands and lets you choose local, project, or user scope.
The hosted endpoint is https://api.githubcopilot.com/mcp/.
The supported local server is the Docker image ghcr.io/github/github-mcp-server.

One easy miss: if your first proof run uses a private repository, GitHub's troubleshooting notes explicitly call out PAT scope problems. If auth looks successful but private repos still do not show up, check the token before you rewrite the config.

One judgment call is worth making up front:

Choose the hosted endpoint first when you want the fewest moving parts and your host version already supports HTTP MCP cleanly.
Choose Docker first when corporate proxy rules block the hosted endpoint, or when you want the GitHub MCP process to stay local and explicit.

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

Cursor Setup

Cursor is the cleaner first host when the evaluation happens inside the editor. The configuration is file-based, which makes it easy to inspect, but it also makes it easy to accidentally hardcode a token into a project file that should never be committed.

The practical split is:

~/.cursor/mcp.json if this is your personal setup and the token should stay on your machine
.cursor/mcp.json if the project really should share the server definition and you have a safe secret strategy

Cursor's MCP docs support variable interpolation in url and headers, so a project file can point at an environment variable instead of a raw token. That is the safer default when the file may be checked into version control.

Add The Hosted GitHub Endpoint In Cursor

If you want the shortest path, put this in your Cursor MCP config and set GITHUB_PAT in your shell or system environment first:

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

If you prefer to follow GitHub's guide exactly, you can replace ${env:GITHUB_PAT} with a literal token string. Do that only in a user-scoped file. Do not commit a project file with a real PAT inside it.

Two version checks matter here:

GitHub's Cursor install guide says the hosted endpoint requires Cursor v0.48.0 or newer for Streamable HTTP support.
GitHub also notes that the GitHub MCP server currently uses a Personal Access Token rather than OAuth.

Use Docker In Cursor If Hosted HTTP Is Blocked

If the hosted endpoint fails behind a firewall or proxy, use the local Docker server instead:

{
  "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 route is slower to get moving because Docker becomes part of the troubleshooting surface. Use it when you need it, not because it feels more "local."

Verify Cursor Before You Ask For Any Real Work

GitHub's guide gives a simple verification loop. Follow it exactly:

Restart Cursor completely.
Open Settings -> Tools & Integrations -> MCP Tools.
Confirm the github server shows a green status dot.
In chat or Composer, confirm that GitHub tools appear under Available Tools.
Test with the smallest request: List my GitHub repositories.

If the green dot never appears, stop there. The most common 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 Setup

Claude Code is the cleaner first host when you want the workflow to stay terminal-native. The scope model is stronger than many people realize, and it is worth using on purpose:

local is the default and stays private to you in the current project
project writes a .mcp.json file meant to be shared in the repo
user makes the server available across projects on your machine

If the token is personal and the setup is just for you, local or user is the right starting point. Use project only when the team genuinely wants a shared MCP definition and the file references environment variables rather than a literal token.

Claude Code's own docs also recommend opening Claude inside the project directory you care about. That keeps the scope obvious and avoids adding a local server in one repo and then wondering why it is missing in another.

Prefer `claude mcp add-json` On Current Claude Code Versions

GitHub's Claude guide says versions 2.1.1 and newer should use claude mcp add-json for the hosted HTTP server:

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

Add --scope user if you want the server across projects:

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

GitHub's guide also points out an annoying edge case on Windows: claude mcp add-json may return Invalid input when adding an HTTP server. If that happens, do not burn time fighting the parser. Use the legacy command format below.

Windows And Older-Version Fallback For Claude Code

For Claude Code 2.1.0 or earlier, GitHub still documents the older HTTP command format:

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

For native Windows PowerShell, GitHub gives this variation:

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

That looks minor, but it is the difference between a working command and a confusing missing required argument 'name' error on Windows.

Use Docker In Claude Code If Hosted HTTP Is Not Viable

If you want the local server or the hosted endpoint is blocked, GitHub's guide uses Docker like this:

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

This is the right fallback when you trust Docker more than the network path. It is not the right default if you are just trying to get the first GitHub workflow running quickly.

Verify Claude Code Before The First Real Task

After setup:

claude mcp list
claude mcp get github

If the server does not appear, check the boring things first:

you added it in the same repo scope you are now testing
the PAT is still valid and has the repo access you need
Docker is running if you chose the local route
you are not mixing the new add-json command with an older Claude version that needs the legacy syntax

Use /mcp inside Claude Code if you need to inspect the configured server or clear and re-add it.

Repo-Context Verification Prompt

Once the server looks healthy, run one narrow task that proves the connection is useful without turning it into a benchmark contest.

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. It tells you whether the host can actually see the repo, whether the issue is readable, and whether the file suggestions are believable. If that fails, adding more MCP servers will only hide the real problem.

What Usually Breaks The First Install

Most failed first runs come from one of these mistakes:

following an older tutorial that still points at @modelcontextprotocol/server-github
saving the config in a scope or file location you are not actually testing from
hardcoding a PAT into a shared config and then refusing to commit it, leaving teammates with a broken file
missing repo access on the PAT when the first test uses private repositories
trying Docker without checking whether Docker is running
trying hosted HTTP on an incompatible host version or through a blocked proxy
setting up both Cursor and Claude Code before one route is already stable

The fix is usually subtraction, not more tooling. Remove the extra uncertainty, get one host reading GitHub correctly, and only then expand the stack.

Which Host To Keep After GitHub Works

Once GitHub MCP is stable, the comparison gets simpler. You are no longer guessing which host might work. You are deciding which surface makes the GitHub context easier to use every day.

Keep the Cursor route if these sound true:

you want GitHub context and file edits in one surface
you care about quick file hopping and inline agent turns
the team already reviews changes from the editor before a PR is fully formed

Keep the Claude Code route if these sound true:

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

The better host is not the one with the fancier demo. It is the one that makes repo context, issue context, and the next implementation step feel easier in your normal lane of work.

Official References

These official sources shaped the setup choices above:

Next Step

If GitHub is now connected and you want the broader stack logic, go back to How To Choose An MCP Server For GitHub Workflows.

If the setup is still failing and the problem feels lower-level than host choice, open Common MCP Server Setup Mistakes.

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

If the server works and the next question is which host to keep, open Cursor vs Claude Code.