How to set up the GitHub MCP server in Claude Code, Cursor, VS Code and Codex
Checked against the official docs:
The official GitHub MCP server lets an AI assistant read repositories and code, work with issues and pull requests, check GitHub Actions runs and review security findings, all in natural language. The easiest setup is GitHub's hosted server: you add one URL and sign in. This guide covers VS Code, Cursor, Claude Code and Codex, when you need a personal access token instead of a browser sign-in, the local Docker option, how to limit tools, and the errors people hit most. It's based on GitHub's MCP docs and the official install guides (checked 20 November 2026).
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.
Quick answer
- Hosted URL:
https://api.githubcopilot.com/mcp/(Streamable HTTP). This is the easiest option and needs no local install. - VS Code (1.101 or later): add that URL (or install from the MCP gallery by searching
@mcp github) and sign in with your GitHub account. OAuth works here. - Cursor (0.48 or later): add the same URL, but include a GitHub personal access token as a Bearer header. GitHub's Cursor guide says the hosted server currently needs a token, not OAuth.
- Claude Code: add the hosted URL with your token in a header (the
claude mcp add-jsoncommand on 2.1.1 or later, orclaude mcp add --transport httpon older versions). - Codex: add the URL in
~/.codex/config.tomland pointbearer_token_env_varat an environment variable that holds your token. - Don't use the old npm package
@modelcontextprotocol/server-github. It has not been supported since April 2025. Use the hosted URL or the official Docker imageghcr.io/github/github-mcp-server.
Free: MCP Starter Checklist
One page: Inspector smoke-test, Claude Code + Cursor connect steps, and the stdout gotcha. Join the list and download it free.
Before you start
- You need a GitHub account. GitHub says the MCP server is available to every GitHub user, on any plan. Some tools still follow the same access rules as the GitHub feature they wrap. For example, tools that talk to Copilot coding agent need a paid Copilot license.
- Prefer the hosted server unless your client can't use remote MCP servers, you want to customize the server, or you are on GitHub Enterprise Server (that product does not host the remote server).
- A personal access token is required for the hosted server in Cursor, Claude Code and Codex. Create a fine-grained or classic token and give it only the permissions you want the assistant to have. Common examples from GitHub's Codex guide are
repofor repository work,workflowfor Actions,read:orgfor organization resources,projectfor classic project boards andgistfor gists. Add more only if a tool fails because of permissions. Store the token in an environment variable or a local secrets file, not in a config you might commit. - The assistant gets the access you grant. A connected client can read and change what that sign-in or token can access, so only connect clients you trust and keep approval on for write actions.
If you belong to a Copilot Business or Copilot Enterprise organization, an admin may need to turn on the "MCP servers in Copilot" policy before MCP works in Copilot. For a shorter overview, see the GitHub MCP Server listing.
What you get by default
If you don't pick toolsets, the server loads the default set: context (who you are and the GitHub context you are in; GitHub strongly recommends this one), repos, issues, pull_requests and users. Other toolsets exist for Actions, Discussions, Projects, Dependabot, code security and more. The hosted server also has a few extra toolsets that the local server does not, including Copilot-related tools.
You don't need to memorize the full tool list. Ask the assistant to list your repositories, summarize a pull request or explain a failing Actions run, and it will pick the matching tools.
VS Code
You need VS Code 1.101 or later for remote MCP and OAuth. The simplest path is the MCP gallery: open the Extensions panel, search @mcp github, install the GitHub MCP server and confirm you trust it. Then open the Command Palette, run MCP: List Servers, and check that GitHub is listed. Switch Copilot Chat to Agent mode so it can use the tools.
To add it by hand, put this in .vscode/mcp.json (note the top-level servers key) and use the Auth CodeLens above the server to sign in with your GitHub account:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/"
}
}
}To use a personal access token instead of OAuth, GitHub's README uses a prompt so the token is not stored in the file:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${input:github_mcp_pat}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "github_mcp_pat",
"description": "GitHub Personal Access Token",
"password": true
}
]
}More on the VS Code files and gallery: how to add an MCP server to VS Code.
Cursor
You need Cursor 0.48 or later for Streamable HTTP. GitHub's Cursor install guide says that while Cursor supports OAuth for some MCP servers, the hosted GitHub server currently needs a personal access token. Add this to ~/.cursor/mcp.json (every project) or .cursor/mcp.json in a project:
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${env:GITHUB_PAT}"
}
}
}
}Set GITHUB_PAT in your shell profile, then restart Cursor so it picks up the variable. Cursor resolves ${env:NAME} in headers, so the token never has to sit in the file. GitHub's own Cursor snippet shows the token written in directly; skip that if the file might be committed. After saving, restart Cursor and check for a green light under Settings → Tools & Integrations → MCP Tools. A first prompt to try: "List my GitHub repositories".
File locations, ${env:} and other Cursor MCP details: how to add an MCP server to Cursor.
Claude Code
On Claude Code 2.1.1 or newer, add the hosted server from a terminal (not from the Claude Code prompt). GitHub's guide shows this add-json form with your token in the header:
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'Prefer pulling the token from an environment variable (Linux or macOS):
export GITHUB_PAT="$(grep '^GITHUB_PAT=' .env | cut -d '=' -f2-)"
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer '"$GITHUB_PAT"'"}}'Add --scope user at the end if you want the server in every project (local is the default, current project only; project writes a shared .mcp.json). Then restart Claude Code and run claude mcp list to confirm it is there. Use /mcp inside Claude Code if you need to inspect it.
If claude mcp add-json returns Invalid input (GitHub documents this on Windows for HTTP servers), or you are on Claude Code 2.1.0 or earlier, use the older command instead:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_GITHUB_PAT"Other Claude Code MCP commands: best MCP servers for Claude Code.
Codex
Edit ~/.codex/config.toml (shared by the CLI and the IDE extension), and read the token from an environment variable. GitHub's Codex guide says --bearer-token-env-var is required for the hosted server:
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"Or from a terminal, after the same environment variable is set:
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKENStart Codex, run /mcp, and check that github shows tools. Then ask it to list your repositories. More on Codex config: how to add an MCP server to Codex.
Local Docker
Use the local server when your client can't reach a remote MCP server, you want to customize flags, or you are on GitHub Enterprise Server. You need Docker installed and running. The official image is ghcr.io/github/github-mcp-server. If a pull fails, GitHub says to run docker logout ghcr.io and try again (an expired login to that registry can block a public image).
On github.com you can sign in with OAuth: the official image already includes the app credentials, it opens a browser login on first use, and it keeps the resulting token in memory only. In Docker you must publish a fixed callback port on loopback so the login can finish:
{
"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"
}
}
}
}A personal access token, if you set one, takes precedence over OAuth:
{
"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"
}
}
}
}Put the token in an environment variable rather than the file when your client supports it. Claude Code can add the same Docker command with claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- docker run -i --rm -p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server. Codex uses the same image in ~/.codex/config.toml with command = "docker" and the matching args and env.
Claude Desktop
Claude Desktop can add remote servers as custom connectors, but GitHub's Claude install guide says the hosted GitHub MCP server is not currently supported that way, because it needs OAuth through a registered GitHub App. Use the local Docker setup above in claude_desktop_config.json instead (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json; Linux: ~/.config/Claude/claude_desktop_config.json). Fully quit and reopen Claude Desktop after saving.
GitHub also notes that some people have run into compatibility issues between Claude Desktop and Docker-based MCP servers, and that they are looking into it. If the local server will not stay connected, try another client for now.
File locations and general Desktop setup: how to add an MCP server to Claude Desktop.
Limit tools and use read-only mode
Turning on only the toolsets you need helps the model pick the right tool and keeps the context smaller. On the hosted server, send the X-MCP-Toolsets header (a comma-separated list, for example repos,issues) or use a toolset-specific URL such as https://api.githubcopilot.com/mcp/x/issues. A URL like that can only name one toolset; to combine several, use the header. The special toolset all enables every toolset (https://api.githubcopilot.com/mcp/x/all on the hosted server, or GITHUB_TOOLSETS=all locally).
To offer only read tools, add readonly at the end of the hosted URL (https://api.githubcopilot.com/mcp/readonly) or set the X-MCP-Readonly header to true. Locally, pass --read-only or set GITHUB_READ_ONLY=1. Read-only mode wins: write tools are skipped even if you also asked for them by name.
Locally, --toolsets or the GITHUB_TOOLSETS environment variable (the environment variable wins if both are set) does the same job, for example GITHUB_TOOLSETS=repos,issues. You can also pass individual tool names with --tools or GITHUB_TOOLS. GitHub also has a lockdown mode (GITHUB_LOCKDOWN_MODE or the X-MCP-Lockdown header) that tries to hide public-repo content from people without push access, as a best-effort filter against prompt injection. It is not an authorization boundary. See GitHub's server configuration guide if you need that.
Check that it works
- Confirm the server is listed and connected in your client (VS Code: MCP: List Servers; Cursor: a green light on the GitHub server; Claude Code:
claude mcp list; Codex:/mcp). - Ask something only this server can do, such as "List my GitHub repositories" or "Summarize the open pull requests in this repo".
- Approve the tool call and check that the result looks like your real GitHub data.
Troubleshooting
- Still running `@modelcontextprotocol/server-github`: that npm package has not been supported since April 2025 and is no longer functional. Switch to the hosted URL or
ghcr.io/github/github-mcp-server. - Authentication failed or 401: the token is missing, expired, or does not have the scopes that tool needs. Create a new token, update the header or environment variable, and restart the client.
- Cursor: Streamable HTTP not working: you need Cursor 0.48 or later. The hosted GitHub server currently needs a Bearer token in Cursor, even though some other remote servers in Cursor can use OAuth.
- Claude Code: `Invalid input` from `add-json`: GitHub documents this on Windows for HTTP servers. Use
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_GITHUB_PAT"instead. On PowerShell, put the server name right afterclaude mcp addif you seemissing required argument 'name'. - Docker image will not pull: run
docker logout ghcr.ioand try again, and check that Docker Desktop (or the Docker engine) is running. - Server listed but no tools: check token scopes, and that you did not narrow toolsets so far that nothing useful remains. Restart the client after changing config.
- Enterprise: GitHub Enterprise Server does not host the remote server, so use local Docker (you will need your own OAuth or GitHub App). For GitHub Enterprise Cloud with data residency, the hosted URL is different; follow GitHub's Enterprise docs rather than the github.com URL in this guide.
FAQ
Do I need GitHub Copilot to use this?
You need a GitHub account. GitHub says the MCP server itself is available on any plan. A few tools still require whatever license the underlying GitHub feature requires, such as a paid Copilot license for Copilot coding agent tools.
Can I use OAuth everywhere?
No. OAuth is the usual path in VS Code for the hosted server, and it works with the official local Docker image on github.com. GitHub's current Cursor guide requires a personal access token for the hosted server. Claude Code and Codex hosted setups in GitHub's install guides also use a token. Claude Desktop cannot add the hosted server as a custom connector today.
Is the token stored if I use Docker OAuth?
GitHub says the official image keeps the OAuth token in memory only. A personal access token in the config, if you set one, takes precedence over OAuth.
How is this different from Playwright or other MCP servers?
This server talks to GitHub's API (repos, issues, pull requests, Actions). It does not drive a web browser. For browser automation, see how to set up the Playwright MCP server.
Sources
Commands and config above come from these official docs. Tools change often, so check them for the latest steps.
- github/github-mcp-server README (remote and local setup, toolsets, read-only mode)
- GitHub MCP Server: remote server docs (URL, headers, toolset paths)
- Install GitHub MCP Server in Cursor
- Install GitHub MCP Server in Claude Applications
- Install GitHub MCP Server in OpenAI Codex
- GitHub docs: Setting up the GitHub MCP Server
PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.
Related guides
Tools in this guide
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.