GitHub MCP Server Cursor IDE Setup 2026 (Repos & Issues — Not Linear)

> Looking for Linear, not GitHub? This page is the GitHub MCP server for Cursor (api.githubcopilot.com / ghcr.io/github/github-mcp-server). For Linear issues, projects, and cycles, use the dedicated Linear MCP server Cursor IDE setup 2026 guide instead — do not reuse this GitHub mcp.json block for Linear.

How do you set up GitHub MCP in Cursor? Add a github entry under mcpServers in ~/.cursor/mcp.json pointed at GitHub's hosted endpoint, https://api.githubcopilot.com/mcp/, with a Personal Access Token in an Authorization: Bearer header. The alternative is the official Docker image, ghcr.io/github/github-mcp-server, run locally with either a PAT or a browser OAuth flow. Restart Cursor, confirm a green status, then ask it something that requires a real GitHub call — listing open issues or PRs on a repo you own is the standard first test.

This page owns GitHub MCP server Cursor IDE setup 2026: the official github/github-mcp-server project, Cursor mcp.json, PAT scopes, Projects toolset, read-only mode, and Cursor MCP log failures. It is GitHub only — repositories, pull requests, issues, Actions, and Projects. It is not Linear, GitLab, Bitbucket, or Jira; those have their own guides.

What changed in GitHub MCP since early 2025

Three dated changes from GitHub's own changelog matter more than a screenshot from last year:

GitHub shipped a Projects toolset on January 28, 2026: projects_list, projects_get, and projects_write replaced a scattered set of earlier project-board calls, and GitHub's own post reported the consolidation cut roughly 23,000 tokens — about half — off the context the server used to spend describing tools before a single call was made. If your mcp.json predates that release and Cursor still shows old, narrower project tools, updating the Docker image or letting the remote endpoint pick up the change is enough; there's no separate opt-in flag.

December 2025 added tool-specific configuration — the ability to enable or disable individual tools, not just whole toolsets, so a team that wants create_pull_request but not merge_pull_request from the same toolset no longer has to choose between granting both or neither. Both the local and remote server were also rewritten from the community mark3labs/mcp-go library onto GitHub's own official Go SDK for MCP around the same time, which is why some pinned older Docker tags behave slightly differently from the current ghcr.io/github/github-mcp-server:latest.

July 2026 brought support for the newer, stateless MCP protocol revision. Practically, this means a fresh HTTP connection no longer needs to replay session state on every call — worth knowing if you're debugging why a proxy or corporate load balancer behaves differently against the GitHub endpoint than it did earlier in the year.

Why the old @modelcontextprotocol/server-github package won't work

If you're following a 2024-era tutorial, stop and check the package name first. The community-maintained @modelcontextprotocol/server-github npm package was superseded by GitHub's own official server, and GitHub's install docs now point exclusively at github/github-mcp-server — either the hosted remote endpoint or the ghcr.io/github/github-mcp-server Docker image. An npx @modelcontextprotocol/server-github block copied from an old blog post may still technically run, but it's not the server GitHub documents or supports, and its tool names and scopes have diverged from the current official server. Use the config below instead.

Quick reference

Prerequisites

Step 1: Create a GitHub Personal Access Token

You need a token even for the OAuth-capable local Docker path if you'd rather skip the browser flow. Fine-grained PATs are the current GitHub recommendation over classic tokens.

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Set an expiration. GitHub does not recommend non-expiring tokens for anything you'll leave configured long-term.
3. Grant repository access scoped to the repos you actually want Cursor touching — not "all repositories" unless you mean it.
4. Under permissions, grant what the toolsets you plan to use require: Contents and Pull requests read/write for the repos and pull_requests toolsets, Issues for the issues toolset, Actions read for the actions toolset, and so on. Start narrow and add scopes when a specific tool call fails with a permissions error rather than granting everything up front.
5. Generate and copy the token. Treat it like a password — never commit it to mcp.json in a shared repo.

Step 2: Add the remote server to Cursor (recommended)

Cursor merges MCP config from two files:

The top-level key is mcpServers. Project-level entries win over global ones with the same server name.

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

Prefer environment interpolation over a hardcoded token so the file stays safe to commit:

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

Save, restart Cursor, and check Settings → Tools & Integrations → MCP Tools for a green dot next to github.

Step 3: Local Docker path (alternative)

Use this when you want the process running on your own machine, you're behind a network policy that blocks the hosted endpoint, or you'd rather authenticate via OAuth instead of pasting a PAT into config.

PAT-based:

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

OAuth-based — the official image ships with an embedded GitHub OAuth app and opens a browser login on first use, keeping the token in memory rather than in a config file:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "127.0.0.1:8085:8085",
        "-e", "GITHUB_OAUTH_CALLBACK_PORT",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_OAUTH_CALLBACK_PORT": "8085"
      }
    }
  }
}

Publish the OAuth callback port to 127.0.0.1 only, not 0.0.0.0 — a wide-open bind exposes the local callback (and briefly, the authorization code) to anything else on your network. If a PAT is also set in env, the server uses the PAT and skips OAuth entirely.

Step 4: Verify the connection

In Cursor chat:

List the open issues in my <owner>/<repo> repository

or

What are the last 5 commits on the main branch of <repo>?

A real, specific answer means the token and toolset cover that action. A permissions error naming a scope tells you exactly what to add back in Step 1.

Controlling which tools Cursor sees: toolsets

Loading every GitHub tool into context hurts tool-selection accuracy and burns tokens on servers you don't use. GitHub's server groups tools into named toolsets, and the default set is intentionally narrow: context, repos, issues, pull_requests, users.

The full toolset list includes actions, code_quality, code_security, copilot, dependabot, discussions, gists, git, labels, notifications, orgs, projects, secret_protection, security_advisories, and stargazers. Enable only what your workflow touches — a team that never uses GitHub Actions doesn't need the actions toolset loaded on every session.

The projects toolset is the January 2026 addition mentioned above: projects_list for enumerating a user's, org's, or repo's projects, projects_get for one project's fields and items, and projects_write for creating or updating items on it. If you were previously working around the lack of a clean Projects toolset with raw GraphQL prompts, drop those and enable projects instead — it's meaningfully cheaper on context than the older workaround.

On the local Docker server, control this with environment variables:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-e", "GITHUB_TOOLSETS", "-e", "GITHUB_READ_ONLY", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT",
        "GITHUB_TOOLSETS": "repos,issues,pull_requests",
        "GITHUB_READ_ONLY": "1"
      }
    }
  }
}

On the remote server, the equivalent controls are HTTP headers rather than env vars: X-MCP-Toolsets for a comma-separated toolset list, and X-MCP-Readonly to register only read tools. There's also a URL-path shorthand — appending /readonly to the endpoint restricts that connection to read-only tools without a header.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/readonly",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_MCP_PAT}",
        "X-MCP-Toolsets": "repos,issues,pull_requests"
      }
    }
  }
}

Read-only mode is worth defaulting to on any repo where you don't want an agent pushing commits, closing issues, or merging PRs on its own initiative.

Practical workflows

Code review before you approve it:

Read PR #212 on this repo, summarize the diff, and flag anything that looks like it changes an existing API contract.

Issue triage:

List open issues labeled "bug" with no assignee, oldest first, and suggest which three look highest-priority based on the title and description.

Cross-referencing Actions failures:

The last Actions run on main failed. Show me the failing job and the relevant log lines.

(Requires the actions toolset enabled.)

PR creation from a local diff:

Open a PR from my current branch to main titled "Fix webhook retry backoff" with a description summarizing the changes.

Cursor will prompt for approval before running write tools by default. Approve read tools like list_issues and get_pull_request freely; slow down on create_pull_request, merge_pull_request, and anything that closes an issue until you've actually read what it's about to do.

Running GitHub MCP next to another issue tracker

Cursor can load multiple MCP servers in one mcp.json. Keep this guide's github entry focused on GitHub credentials and toolsets. If your team tracks work in Linear, add that server from the Linear MCP Cursor setup guide guide — that page owns the Linear remote URL, API key header, Docker/OAuth options, and toolsets. Do not treat this GitHub article as the Linear setup.

Troubleshooting

Server never appears in Cursor. Confirm the file is .cursor/mcp.json or ~/.cursor/mcp.json, the top-level key is mcpServers (not VS Code's servers), and the JSON is valid — one syntax error drops every server defined in that file.

Remote endpoint fails to connect. Confirm you're on Cursor 0.48.0+ for Streamable HTTP. Check curl -I https://api.githubcopilot.com/mcp/ from the same machine — a 404/405 means the endpoint is reachable (most MCP endpoints only answer POST), while no response at all points at a firewall or proxy blocking outbound HTTPS.

401 or 403 on every call. The PAT is expired, missing the scope the specific tool needs, or wasn't copied correctly (watch for trailing whitespace pasted into the header value). Regenerate and update the config.

Tools list is empty or almost empty. If you're on the remote endpoint with a GITHUB_TOOLSETS-style env var in your config, that variable does nothing there — it's a local-Docker-only control. Use X-MCP-Toolsets as a header on the remote path instead.

OAuth in Docker never finishes. Confirm the port mapping is exactly 127.0.0.1:8085:8085 and nothing else on your machine already holds port 8085. If a PAT is also set in the env block, it silently takes precedence and OAuth won't trigger at all — remove it if you actually want the browser flow.

Writes fail, reads work. Read-only mode is on somewhere in the chain (/readonly in the URL, X-MCP-Readonly header, or GITHUB_READ_ONLY env var on the local server) — or the PAT itself lacks write scope for that resource. Check both.

Green server, but Cursor's agent says the tool wasn't found. This has been reported on some Cursor builds for HTTP-based MCP servers specifically. Try a fresh Agent chat, or Settings → Network → HTTP Compatibility Mode → http/1.1, then restart Cursor. It's usually a Cursor-side quirk, not a GitHub API outage.

GitHub MCP works locally but a Background Agent / Cloud Agent can't see your repos. A local mcp.json entry doesn't travel with a Background Agent — Cursor injects secrets for cloud agents separately, via Settings → Background Agents → Secrets, as encrypted environment variables at runtime. A PAT sitting in your local ~/.cursor/mcp.json isn't automatically available there. Add the token as a named secret in that panel and reference it the same way (${env:GITHUB_MCP_PAT} or similar) in the agent's config, and note that an agent already running won't pick up a secret you just added — start a new one after saving it.

GitHub MCP fails inside a Cursor Dev Container with spawn docker ENOENT. This happens when mcp.json uses the local Docker path from Step 3, but the Docker CLI isn't available inside the dev container itself — a container generally can't launch sibling Docker processes on the host without extra setup. The fix that needs no extra dev container configuration is to switch that entry to the remote endpoint from Step 2 (https://api.githubcopilot.com/mcp/ with a PAT header) — it's a plain HTTPS call, so it needs neither Docker nor Node.js running inside the container at all.

Editing mcp.json doesn't seem to change anything until you fully quit Cursor. Cursor doesn't always hot-reload MCP config changes on save. Before assuming the config itself is wrong, try Settings → Tools & Integrations → MCP Tools and toggle the github server off and back on — that alone resolves it more often than a full restart does, and it's faster to try first.

When not to use this

Don't wire the actions or write-capable pull_requests toolset into a fully autonomous agent loop that merges its own PRs on a repo with an auto-deploy pipeline on main. Read-only mode plus a human approving every write tool call is the safer default — an agent that's confidently wrong about "this diff is safe to merge" is a bad thing to discover after it's already deployed.

Frequently Asked Questions

What's the short version of GitHub MCP Cursor setup? Add a github key under mcpServers in mcp.json with url set to https://api.githubcopilot.com/mcp/ and an Authorization: Bearer header carrying a fine-grained PAT, or run the ghcr.io/github/github-mcp-server Docker image locally with a PAT or OAuth. Restart Cursor and confirm the green dot before asking it anything.

Does this work with GitHub Enterprise Cloud? Yes, with data residency — use https://copilot-api.{subdomain}.ghe.com/mcp in place of the standard endpoint, replacing {subdomain} with your enterprise's subdomain.

Do I need Docker at all? No — Docker is only required for the local server path. The hosted remote endpoint needs nothing but a token and network access.

Can I scope this to one repository? Not at the config level. Scope the PAT's repository access to just the repos you want reachable (Step 1) rather than relying on a prompt-level restriction, since a broad-scoped token can still be asked about any repo it can see.

What's different between this and GitHub Copilot's built-in tools in an IDE? This is the standalone GitHub MCP server, usable from any MCP-compatible client including Cursor. It's the same underlying server GitHub documents for Copilot's own MCP integration, just wired into a different client here.

PAT or OAuth — which should I use? OAuth (local Docker path) if you don't want a long-lived token sitting in a config file. PAT if you're on the remote hosted endpoint, since that path doesn't do an interactive browser login — it authenticates purely on the bearer token in the header.

Can I run GitHub MCP next to another MCP server in Cursor? Yes. Cursor merges multiple mcpServers entries in the same mcp.json. Keep GitHub's PAT on the GitHub entry only. For Linear-specific remote URL, API key, Docker, and toolsets, use the Linear MCP Cursor setup guide guide rather than this page.

Does a GitHub MCP Cursor setup that works locally also work in a Background Agent? Not automatically. Background Agents and Cloud Agents don't read your local ~/.cursor/mcp.json secrets — Cursor injects secrets for those separately as encrypted environment variables via Settings → Background Agents → Secrets. Add the PAT there too, and start a new agent after saving it, since an already-running agent won't pick up a secret added mid-session.

Does GitHub MCP work inside a Cursor Dev Container? Not with the local Docker path from Step 3 — a dev container generally can't spawn a sibling Docker process on the host, which surfaces as spawn docker ENOENT. Switch that entry to the remote endpoint from Step 2 instead (https://api.githubcopilot.com/mcp/ with a PAT in the Authorization header); it's a plain HTTPS call with no Docker or Node dependency inside the container.

Related guides

Official docs cited