# GitHub MCP server and GitHub API: setup in Claude, Cursor and ChatGPT, tokens, rate limits and errors

GitHub's official MCP server, [github/github-mcp-server](https://github.com/github/github-mcp-server), gives Claude, Cursor, VS Code, ChatGPT and other assistants tools for repositories, issues, pull requests, Actions and security alerts. Use the hosted version at `https://api.githubcopilot.com/mcp/` with a personal access token (or one-click OAuth in VS Code), or run it locally with Docker or the binary; it is free for every GitHub plan, and read-only mode is one URL suffix (`/readonly`) away. For your own code, the GitHub REST API at `https://api.github.com` allows 60 requests an hour without a token and 5,000 with one.

Every command, limit and error below was read from GitHub's, Anthropic's and OpenAI's own documentation, or recorded from live requests, on 2026-11-15. The server was at v2.1.0 (released November 3, 2026) with 34,491 stars.

## The GitHub MCP server in November 2026

GitHub builds and maintains the server in Go under the MIT license, and the hosted endpoint is built from the same code. Two facts most guides still miss: version 2.0.0 shipped on October 6, 2026, and the local server can log you in with OAuth in a browser, so a personal access token is optional for local use on github.com.

| | Remote (hosted by GitHub) | Local (Docker or binary) |
|---|---|---|
| Address | `https://api.githubcopilot.com/mcp/` (streamable HTTP) | `ghcr.io/github/github-mcp-server`, or `github-mcp-server stdio` |
| Auth | OAuth in VS Code, Visual Studio and JetBrains; a PAT in the `Authorization` header everywhere else | Browser OAuth on first run (token kept in memory), or `GITHUB_PERSONAL_ACCESS_TOKEN` |
| Pick tools | URL path (`/x/issues`) or `X-MCP-Toolsets` and `X-MCP-Tools` headers | `--toolsets`, `--tools` or `GITHUB_TOOLSETS`, `GITHUB_TOOLS` |
| Read-only | `/readonly` suffix or `X-MCP-Readonly: true` | `--read-only` or `GITHUB_READ_ONLY=1` |
| Extra | Copilot coding agent, Copilot Spaces and GitHub support docs search | Bundled workflow skills with `--features=skills` |
| GitHub Enterprise Server | Not supported | Supported with `GITHUB_HOST` |

GitHub's docs say the server "is available to all GitHub users regardless of plan type", but a tool needs whatever plan its feature needs, so the Copilot coding agent tool needs a paid Copilot license. In organizations on Copilot Business or Enterprise, an admin must turn on the "MCP servers in Copilot" policy for MCP to work inside Copilot. The server is listed in the official MCP registry as `io.github.github/github-mcp-server`, version 2.1.0, with the remote URL and the Docker image.

The old npm package `@modelcontextprotocol/server-github` is archived. Its last version, 2025.4.8, carries the npm notice "Archived and unmaintained; no security guarantees", so replace any config that still runs it through `npx`.

## Toolsets, read-only mode and lockdown mode

With no configuration the server loads five toolsets: `context`, `repos`, `issues`, `pull_requests` and `users`. The README lists 92 tools across 22 toolsets; loading all of them fills an assistant's context, so turn on only what a task needs.

| Toolset | What it covers |
|---|---|
| `context` | Who you are and where you are working (GitHub recommends keeping it on) |
| `repos`, `git` | Files, branches, commits, releases, tags, low-level Git objects |
| `issues`, `labels` | Read, create and edit issues, sub-issues, comments and labels |
| `pull_requests` | Read diffs and files, review, comment, create, update, merge |
| `actions` | Workflow runs, job logs, triggering runs |
| `code_security`, `dependabot`, `secret_protection`, `security_advisories`, `code_quality` | Alerts and advisories |
| `discussions`, `gists`, `notifications`, `projects`, `orgs`, `stargazers`, `governance` | The rest of GitHub |
| `copilot`, `copilot_spaces`, `github_support_docs_search` | Remote-only Copilot tools and GitHub's support docs |

On the remote server each toolset has its own URL (`https://api.githubcopilot.com/mcp/x/actions`, `.../x/all`), and only one toolset fits in the path. To combine several, send a header such as `X-MCP-Toolsets: repos,issues`. Unknown toolset names are ignored silently, while an unknown tool name in `X-MCP-Tools` stops the server from starting.

**Read-only mode** removes every tool that writes. On the remote server add `/readonly` to any URL (`https://api.githubcopilot.com/mcp/readonly`, `https://api.githubcopilot.com/mcp/x/issues/readonly`). Read-only wins over an explicit tool list, so a write tool named in `--tools` is still skipped.

**Lockdown mode** (`--lockdown-mode`, `GITHUB_LOCKDOWN_MODE=1` or `X-MCP-Lockdown: true`) hides issue and pull request content written by people without push access to a public repository, which cuts the risk of prompt injection from strangers' comments. GitHub calls it "a best-effort content filter" that is "not an authorization boundary": the token can still reach that content through other tools.

## Getting a GitHub token step by step

GitHub has no "API key". The REST API, the GraphQL API and the MCP server all take a token, and for your own scripts and assistants that token is a personal access token (PAT). GitHub recommends fine-grained PATs over classic ones.

1. Verify the email address on your GitHub account if you have not.
2. Open **Settings > Developer settings > Personal access tokens > Fine-grained tokens**, or go straight to [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new).
3. Name the token and pick an **Expiration**. The default is 30 days; you can choose up to 366 days or no expiry, unless your organization sets a maximum lifetime.
4. Pick the **Resource owner**: your account or one organization. A fine-grained token reaches one owner only.
5. Under **Repository access**, choose **Only select repositories** and pick them. Every token can read all public repositories regardless.
6. Under **Permissions**, grant the least you need (see the table below), then **Generate token** and copy it. GitHub shows it once.

If the owner is an organization that requires approval, the token stays `pending` and can read only public data until an admin approves it. Fine-grained tokens start with `github_pat_`; classic tokens start with `ghp_`.

You can also pre-fill the form with a link. This opens a 30-day, read-only token for repository contents:

```text
https://github.com/settings/personal-access-tokens/new?name=MCP+read+token&expires_in=30&contents=read&issues=read&pull_requests=read
```

| Task | Fine-grained permissions | Classic scope |
|---|---|---|
| Read code, issues and PRs (read-only MCP) | Contents: read, Issues: read, Pull requests: read (Metadata: read is added automatically) | `repo` (public repos only: no scope) |
| Open issues and comment | Issues: read and write | `repo` or `public_repo` |
| Push commits and open PRs | Contents: write, Pull requests: write | `repo` |
| Edit workflow files | Workflows: write | `workflow` |
| Read Actions runs and logs | Actions: read | `repo` |
| Org teams and members | Members: read (organization permission) | `read:org` |

Use a classic token only where a fine-grained one cannot work. GitHub lists the gaps: contributing to public repositories you are not a member of, working as an outside collaborator, reaching several organizations with one token, Packages, the Checks API, and Projects owned by a user account. A classic token reaches every repository you can, and organizations can block classic tokens outright (requests then fail with 403). You can hold at most 50 fine-grained tokens, and GitHub deletes tokens unused for a year.

For automation that acts as an organization or a bot rather than as you, GitHub points to a **GitHub App**: it gets fine-grained permissions, is installed on chosen repositories, and mints installation tokens (prefix `ghs_`) that expire after 1 hour, signed with a JWT that may live at most 10 minutes. Inside GitHub Actions, use the built-in `GITHUB_TOKEN` instead of a PAT.

## Add the GitHub MCP server to Claude Code

Claude Code connects to the hosted server with one command; run it in your terminal, not inside a Claude Code session. GitHub's guide uses a PAT in the header:

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

For read-only access, point it at the read-only URL instead:

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

GitHub's guide also gives the JSON form for Claude Code 2.1.1 and later, and notes that on Windows `add-json` can return `Invalid input` for HTTP servers, in which case use the command above:

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

To run it locally with no token at all, let the Docker image log you in through the browser on first use:

```bash
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
```

The default scope is `local` (you, this project). Add `--scope user` for every project, or `--scope project` to write a shared `.mcp.json`; if you do that, keep the token out of the file and out of git. Check the result with `claude mcp list` and `claude mcp get github`, or `/mcp` inside a session.

Claude Code does not need the MCP server to use GitHub at all: it can run `git` and the `gh` CLI in your terminal. The MCP server adds structured tools for issues, reviews, Actions logs and alerts. To have Claude answer `@claude` mentions in pull requests and issues, run `/install-github-app` in Claude Code, which installs the Claude GitHub App, stores `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` as a repository secret and opens a pull request with the workflow from [anthropics/claude-code-action](https://github.com/anthropics/claude-code-action).

## Claude Desktop and Claude's GitHub integration

Claude has two separate GitHub routes. The **GitHub Integration** in claude.ai and the desktop app reads repository files; the **GitHub MCP server** works issues, pull requests and Actions.

**The GitHub Integration** is built into Claude, available on every plan including Free, and managed in **Customize > Connectors > GitHub Integration > Connect**. After you connect, the **+** menu in a chat shows **Add from GitHub**; in a private project, project knowledge has a **GitHub** option with a file picker and **Sync now**. Per Anthropic's docs it reads file names, file contents and branch content only, with no commit history, pull requests, issues or repository metadata. For a private repository Claude cannot reach yet, the dialog links to the Claude GitHub App installation, where you grant access to all or selected repositories or request it from an organization admin. On Team and Enterprise plans an admin must turn GitHub on in **Organization settings > Connectors**.

**The GitHub MCP server in Claude Desktop** runs locally. GitHub's guide says the remote server cannot be added as a custom connector because it "requires OAuth authentication through a registered GitHub App (or OAuth App)". Open **Settings > Developer > Edit Config** and add this to `claude_desktop_config.json` (`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS, `~/.config/Claude/` on Linux), then restart Claude:

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

Drop the two `GITHUB_READ_ONLY` entries to allow writes. Without Docker, download a release binary, put it on your `PATH`, and use `"command": "github-mcp-server", "args": ["stdio"]` with the same `env`.

## Cursor

Cursor takes the hosted server with a PAT; GitHub's guide says Cursor needs v0.48.0 or later and that "the GitHub server currently requires a Personal Access Token" there. Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project) and restart Cursor:

```json
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT",
        "X-MCP-Toolsets": "repos,issues,pull_requests,actions"
      }
    }
  }
}
```

A green dot under **Settings > Tools & Integrations > MCP Tools** means it connected. The local Docker entry from the Claude Desktop section also works in Cursor.

## VS Code and other Copilot IDEs

VS Code 1.101 and later can sign in to the hosted server with OAuth, so no token is needed. Search `@mcp github` in the Extensions view and click **Install**, or add this to `.vscode/mcp.json`:

```json
{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}
```

Visual Studio 17.14 and later and the JetBrains Copilot plugin also do one-click OAuth with the same URL. Enterprise Managed Users have PATs disabled by default, so OAuth is their route. GitHub publishes install guides for Codex, Windsurf, Zed, Gemini CLI, OpenCode and others in the repository's [installation guides](https://github.com/github/github-mcp-server/tree/main/docs/installation-guides).

## ChatGPT and GitHub

ChatGPT's own GitHub app is read-only and is the supported route. Open **Settings > Plugins > GitHub**, authorize the ChatGPT app on GitHub, and select the repositories it may read. OpenAI's help article says ChatGPT then "can retrieve permitted repository content on demand", that repositories "generally take about 5 minutes" to appear, and that availability varies by plan, so some accounts see GitHub in deep research or agent mode but not in standard chat. It cannot push code or open pull requests; OpenAI points to Codex for that, and GitHub has a Codex install guide for the MCP server.

Adding GitHub's MCP server to ChatGPT as a custom server is harder. ChatGPT adds remote servers under **Plugins > + > Add custom MCP server** and supports OAuth (static client credentials, client metadata documents or dynamic client registration) or no auth, with no field for a bearer header. GitHub's authorization server advertises S256 PKCE and device code but no registration endpoint, so ChatGPT would need the client ID and secret of a GitHub OAuth App you register yourself. Neither company documents that setup, and we did not test it.

## GitHub REST API endpoints

The REST API lives at `https://api.github.com`. Send `Accept: application/vnd.github+json`, a `User-Agent` (requests without one get a 403), and `X-GitHub-Api-Version`. Two versions are live: `2026-03-10`, released March 10, 2026, and `2022-11-28`, the default when you send no header, supported until March 10, 2028.

| Endpoint | Returns | Token needed | Fine-grained permission |
|---|---|---|---|
| `GET /user` | The token's own account | Yes | None |
| `GET /users/{username}` | A public profile | No | None |
| `GET /repos/{owner}/{repo}` | Repository details, stars, default branch | Private repos only | Metadata: read |
| `GET /repos/{owner}/{repo}/contents/{path}` | A file (Base64) or a directory listing; full support up to 1 MB | Private repos only | Contents: read |
| `GET /repos/{owner}/{repo}/issues` | Open issues, pull requests included (they carry a `pull_request` key) | Private repos only | Issues: read |
| `POST /repos/{owner}/{repo}/issues` | Creates an issue | Yes | Issues: write |
| `GET /repos/{owner}/{repo}/pulls` | Pull requests | Private repos only | Pull requests: read |
| `GET /repos/{owner}/{repo}/commits` | Commit history | Private repos only | Contents: read |
| `GET /repos/{owner}/{repo}/releases/latest` | The latest release | Private repos only | Contents: read |
| `GET /repos/{owner}/{repo}/actions/runs` | Workflow runs | Private repos only | Actions: read |
| `GET /search/repositories?q=` | Repositories matching a query | No | None |
| `GET /search/issues?q=` | Issues and PRs; `search_type=semantic` or `hybrid` needs a token | No (semantic: yes) | None |
| `GET /search/code?q=` | Code matches | Yes | None |
| `GET /rate_limit` | Your remaining budget per resource | No | None |
| `GET /versions` | Supported API versions | No | None |

List endpoints return 30 items by default and up to 100 with `per_page=100`; a larger value is cut to the maximum without an error. Follow the `Link` header's `rel="next"` URL for more pages. Search returns at most 1,000 results per query, and the query text may be at most 256 characters, not counting qualifiers.

The **GraphQL API** is a single endpoint, `POST https://api.github.com/graphql`, and always needs a token. It lets you fetch nested data in one call (a repository, its open issues and their labels), with every connection limited by a `first` or `last` argument and at most 500,000 nodes per query. GitHub maintains official Octokit libraries for JavaScript, Ruby and .NET, and its docs list third-party libraries for other languages.

## GitHub API rate limits

The REST API counts requests per hour by identity, and search and GraphQL have their own buckets. These are GitHub's figures as of November 2026.

| Who is calling | REST (core) | Search | GraphQL |
|---|---|---|---|
| No token (per IP address) | 60 / hour | 10 / minute; code search not allowed | Not allowed |
| PAT, OAuth app token or GitHub App user token (shared per user) | 5,000 / hour | 30 / minute; code search 10 / minute | 5,000 points / hour |
| GitHub App installation | 5,000 / hour, plus 50 per repo over 20 and 50 per user over 20, up to 12,500 | 30 / minute | Same scaling, up to 12,500 points |
| App or installation owned by a GitHub Enterprise Cloud org | 15,000 / hour | 30 / minute | 10,000 points / hour |
| `GITHUB_TOKEN` in Actions | 1,000 / hour per repository | 30 / minute | 1,000 points / hour |

All of a user's tokens share the 5,000: a PAT, an OAuth app and a GitHub App acting for you draw on the same budget. Every response carries `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-used`, `x-ratelimit-reset` (Unix seconds) and `x-ratelimit-resource`; our unauthenticated calls showed `60` and `core`, and a search showed `10` and `search`. `GET /rate_limit` does not count against the primary limit. Version 2026-03-10 dropped the old top-level `rate` field from that endpoint; read `resources.core`.

**Secondary limits** apply on top of those, and GitHub may change them without notice:

- no more than 100 concurrent requests across REST and GraphQL;
- no more than 900 points a minute to one REST endpoint, or 2,000 for GraphQL (a GET costs 1 point, a POST, PATCH, PUT or DELETE costs 5);
- no more than 90 seconds of CPU time per 60 seconds, 60 of them for GraphQL;
- no more than 80 content-creating requests a minute and 500 an hour;
- no more than 2,000 OAuth token requests an hour per app.

Hitting either kind returns 403 or 429. If `retry-after` is present, wait that many seconds; if `x-ratelimit-remaining` is `0`, wait until `x-ratelimit-reset`; otherwise wait at least a minute and back off exponentially. GitHub warns that continuing to send requests while limited "may result in the banning of your integration". A request that runs past 10 seconds is cut off, and a GraphQL timeout also costs extra points for the next hour.

## Python example: REST with pagination and rate-limit handling

This script needs only `requests`. Without `GITHUB_TOKEN` it runs on the 60-an-hour budget, which is how we ran it on 2026-11-15; it printed the repository, its five latest releases, ten search hits and the remaining budget.

```python
import os
import time

import requests

API = "https://api.github.com"
TOKEN = os.environ.get("GITHUB_TOKEN")  # fine-grained PAT; leave unset for 60 requests/hour

session = requests.Session()
session.headers.update({
    "Accept": "application/vnd.github+json",
    "X-GitHub-Api-Version": "2026-03-10",
    "User-Agent": "my-github-script",  # GitHub rejects requests with no User-Agent
})
if TOKEN:
    session.headers["Authorization"] = f"Bearer {TOKEN}"


def gh_get(url, params=None, retries=3):
    """GET one page; wait out primary and secondary rate limits."""
    for attempt in range(retries + 1):
        resp = session.get(url, params=params, timeout=30)
        if resp.status_code in (403, 429) and attempt < retries:
            if resp.headers.get("retry-after"):
                wait = int(resp.headers["retry-after"])
            elif resp.headers.get("x-ratelimit-remaining") == "0":
                wait = int(resp.headers["x-ratelimit-reset"]) - int(time.time()) + 1
            else:
                wait = 60 * (2 ** attempt)  # secondary limit with no hint
            if wait > 900:
                raise RuntimeError(f"Rate limited for {wait}s: {resp.json().get('message')}")
            time.sleep(max(wait, 1))
            continue
        if resp.status_code >= 400:
            raise RuntimeError(f"{resp.status_code}: {resp.json().get('message')}")
        return resp
    raise RuntimeError("Still rate limited after retries")


def gh_paginate(path, params=None, max_items=500):
    """Follow the Link header (rel="next") until max_items."""
    url = f"{API}{path}"
    params = {"per_page": 100, **(params or {})}
    items = []
    while url and len(items) < max_items:
        resp = gh_get(url, params)
        data = resp.json()
        items.extend(data["items"] if isinstance(data, dict) and "items" in data else data)
        url = resp.links.get("next", {}).get("url")
        params = None  # the next URL already carries the query string
    return items[:max_items]


if __name__ == "__main__":
    repo = gh_get(f"{API}/repos/github/github-mcp-server").json()
    print(repo["full_name"], repo["stargazers_count"], "stars, pushed", repo["pushed_at"])

    releases = gh_paginate("/repos/github/github-mcp-server/releases", max_items=5)
    for rel in releases:
        print(rel["tag_name"], rel["published_at"])

    found = gh_paginate("/search/repositories",
                        {"q": "mcp server language:python stars:>1000", "sort": "stars"},
                        max_items=10)
    for r in found:
        print(f'{r["stargazers_count"]:>7}  {r["full_name"]}')

    limits = gh_get(f"{API}/rate_limit").json()["resources"]
    print("core left:", limits["core"]["remaining"], "search left:", limits["search"]["remaining"])
```

## Python example: GraphQL in one request

GraphQL needs a token and charges points by how many nodes a query could return; ask for `rateLimit { cost }` to see the price of each query. A response can carry an `errors` array next to `data`, so check for it as well as the HTTP status.

```python
import os

import requests

query = """
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    stargazerCount
    issues(states: OPEN, first: 5, orderBy: {field: CREATED_AT, direction: DESC}) {
      nodes { number title createdAt }
    }
  }
  rateLimit { cost remaining resetAt }
}
"""

resp = requests.post(
    "https://api.github.com/graphql",
    json={"query": query, "variables": {"owner": "github", "name": "github-mcp-server"}},
    headers={"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"},  # GraphQL always needs a token
    timeout=30,
)
resp.raise_for_status()
body = resp.json()
if "errors" in body:
    raise RuntimeError(body["errors"])
repo = body["data"]["repository"]
print(repo["stargazerCount"], "stars")
for issue in repo["issues"]["nodes"]:
    print(issue["number"], issue["createdAt"], issue["title"])
print("cost:", body["data"]["rateLimit"]["cost"], "points left:", body["data"]["rateLimit"]["remaining"])
```

## GitHub API errors and fixes

GitHub returns errors as JSON with `message`, `documentation_url` and `status`. These bodies were recorded on 2026-11-15.

A wrong, expired or revoked token, on any endpoint:

```json
{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest",
  "status": "401"
}
```

No token on an endpoint that needs one, such as `GET /user` or code search:

```json
{
  "message": "Requires authentication",
  "documentation_url": "https://docs.github.com/rest",
  "status": "401"
}
```

A repository that does not exist, or a private one your token cannot see. GitHub returns 404 rather than 403 "to avoid confirming the existence of private repositories":

```json
{"message":"Not Found","documentation_url":"https://docs.github.com/rest/repos/repos#get-a-repository","status":"404"}
```

A primary rate limit, here from GraphQL with no token (the real body names your IP address):

```json
{"message":"API rate limit exceeded for <your IP>. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)","documentation_url":"https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"}
```

An unsupported `X-GitHub-Api-Version`, which returns 400:

```json
{"message":"Bad Request","errors":"The version you specified in the \"X-GitHub-API-Version\" request header, \"2020-01-01\", is not a supported version. The following versions are currently supported: \"2026-03-10\" (most recent) and \"2022-11-28\".","documentation_url":"https://docs.github.com/rest","status":"400"}
```

| Status and message | Cause | Fix |
|---|---|---|
| 401 "Bad credentials" | Token mistyped, expired, revoked, or the `Authorization` header is malformed | Send `Authorization: Bearer <token>`; make a new token |
| 401 "Requires authentication" | No token on `/user`, code search, semantic search or GraphQL | Add a token |
| 403 "API rate limit exceeded", `x-ratelimit-remaining: 0` | Primary limit (60 an hour without a token) | Wait until `x-ratelimit-reset`; authenticate |
| 403 or 429 "secondary rate limit" | Too many concurrent or rapid requests, or too much content created | Honor `retry-after`, else wait a minute and back off |
| 403 "Resource not accessible by personal access token" (or "by integration") | Fine-grained PAT or GitHub App lacks a permission | Read the `X-Accepted-GitHub-Permissions` response header and add that permission |
| 403 on an organization's repositories with a classic PAT | The organization blocks classic tokens | Use a fine-grained PAT or a GitHub App |
| 403 plain text "Request forbidden by administrative rules" | No `User-Agent` header | Send a `User-Agent` |
| 404 "Not Found" on a repo you can open in the browser | Token cannot see it: wrong resource owner, repo not selected, missing scope, or a trailing slash or wrong HTTP method | Check the token's owner and repository list; check the URL |
| 400 unsupported version | Bad `X-GitHub-Api-Version` value | Use `2026-03-10` or `2022-11-28` |
| 410 Gone | An API version past its end of support | Move to a supported version |
| 422 "Validation Failed" | Missing or invalid field; `errors[].code` says which (`missing_field`, `invalid`, `already_exists`) | Fix the request body |

The hosted MCP server answers a request with no token with HTTP 401, the text `bad request: missing required Authorization header`, and a `www-authenticate` header pointing to its OAuth metadata. In an assistant this shows as the server failing to connect or listing no tools: check the token in the header, its expiry, and that it can see the repositories you ask about. GitHub's Claude guide gives `claude mcp list` and `/mcp` for Claude Code, and the `mcp-server-*.log` files in Claude's logs folder for Claude Desktop.

## Choosing a route

Pick the route by what you want the assistant or script to do.

| You want to | Use |
|---|---|
| Ask Claude about a repository's code in chat | Claude's GitHub Integration (Customize > Connectors), free on every plan |
| Ask ChatGPT about your code | ChatGPT's GitHub app (Settings > Plugins), read-only |
| Let Claude Code, Cursor or VS Code work issues, PRs and Actions | The hosted MCP server with a fine-grained PAT; add `/readonly` until you trust it |
| Keep everything on your machine, or use GitHub Enterprise Server | The local server in Docker or as a binary |
| Have Claude respond to `@claude` in PRs | `/install-github-app` in Claude Code (Claude Code GitHub Actions) |
| Script data pulls or reports | REST API with a fine-grained PAT; GraphQL for nested data in one call |
| Run automation for an organization or many repositories | A GitHub App with installation tokens |

For research questions that need GitHub alongside other sources, Hyperresearch finds GitHub repositories and issues by search and reads each page itself, one of the sources listed on [/sources](/sources).

Related guides: [Reddit MCP servers and the Reddit API](/guides/reddit-mcp), [X API pricing, keys and MCP](/guides/x-api), [MCP servers for research data](/guides/research-data-mcp-servers) and [Claude Code as a research harness](/guides/claude-code-research-harness).

## Sources

- GitHub: [github/github-mcp-server](https://github.com/github/github-mcp-server) README, [remote server docs](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md), [Claude install guide](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md), [Cursor install guide](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md)
- GitHub Docs: [Setting up the GitHub MCP server](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/set-up-the-github-mcp-server), [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api), [Search](https://docs.github.com/en/rest/search/search), [GraphQL rate and query limits](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api), [Troubleshooting the REST API](https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api), [API versions](https://docs.github.com/en/rest/about-the-rest-api/api-versions)
- Anthropic: [Claude GitHub integration](https://claude.com/docs/connectors/github), [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions)
- OpenAI: [Connecting GitHub to ChatGPT](https://help.openai.com/en/articles/11145903-connecting-github-to-chatgpt), [Developer mode and custom MCP servers](https://developers.openai.com/api/docs/guides/developer-mode)
- [Official MCP registry](https://registry.modelcontextprotocol.io) entry `io.github.github/github-mcp-server`
