Error GITHUB_PERSONAL_ACCESS_TOKEN not set

Not specified by the original author.

Fix GitHub MCP Error: GITHUB_PERSONAL_ACCESS_TOKEN not set when using the OAuth config

TL;DR

The docs' OAuth setup is not in the released image yet. Either use a classic personal access token (PAT) in the config, or run a build that actually contains the OAuth code. The error message is misleading: it says nothing about OAuth or versions.

The exact error:

Error: GITHUB_PERSONAL_ACCESS_TOKEN not set

Steps

1. Check which image you pulled

docker images ghcr.io/github/github-mcp-server --format "{{.Tag}}"

Success check: if it says latest resolving to v1.4.0, that image predates the OAuth feature. The OAuth login code merged to main after the v1.4.0 release, so it is not in the image.

2. Switch to a PAT (the fix that works today)

Generate a fine-grained PAT at your GitHub settings page with the scopes you need, then use the PAT config instead of the OAuth config:

{
  "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 personal access token]" }
    }
  }
}

Success check: the server starts and list_repos or a similar tool call works.

3. Or run a build with the OAuth code

If you specifically need the OAuth flow, build from main or wait for a release newer than v1.4.0, then keep the documented GITHUB_OAUTH_CALLBACK_PORT config.

Success check: the server prompts a browser-based login on first use instead of exiting.

When this applies

• You copied the OAuth install config from the docs (it passes GITHUB_OAUTH_CALLBACK_PORT).
• docker run exits immediately with Error: GITHUB_PERSONAL_ACCESS_TOKEN not set.

When it does not apply

• You are already using a PAT and still get the error. Then the token genuinely is not reaching the container: check the -e flag and the env block, and check the token has not expired.
• Docker itself fails (ghcr.io pull error). Try docker logout ghcr.io and restart.
• Claude Desktop says "command is undefined". Claude Desktop does not support type: http configs; use the Docker stdio setup above.

Tool compatibility

• ghcr.io/github/github-mcp-server Docker image (v1.4.0 and earlier)
• Claude Desktop, Claude Code, Cursor
• Docker required for the image-based setup

Why it happens

Docs and code shipped out of order. The install guide was updated to lead with OAuth login, but the OAuth implementation merged to main after the last tagged release, so the image everyone pulls (latest = v1.4.0) only knows the PAT path. With no PAT in the environment, the server exits with the PAT error, which reads as if you misconfigured the token rather than ran an image that lacks the feature.

Edge cases

• --insiders builds also lack the feature on the released image; the flag does not help here.
• PATs expire; if this error appears months after a working setup, regenerate the token before re-diagnosing.
• For Claude Code, some users switch to the remote endpoint over HTTP with an Authorization header instead of Docker; that is a separate, supported path.

The github-mcp-server issue thread reports that the install docs on main lead the local stdio setup with an OAuth config passing GITHUBOAUTHCALLBACKPORT, but that feature is not in any released image: latest resolves to v1.4.0 (2026-06-18) while the OAuth code merged after the release. Anyone copying the documented OAuth config and pulling latest gets Error: GITHUBPERSONALACCESSTOKEN not set, which never mentions OAuth or a version requirement. Verified fixes from the thread: use a personal access token instead of the OAuth config, or run a build that contains the OAuth code. Source: https://github.com/github/github-mcp-server/issues/2779

Not specified by the original author.

TL;DR

Unauthenticated GitHub search hits the harsh anonymous rate limit fast. Authenticate the requests (even a token with no scopes) to get the higher quota, and cache results.

Error

API rate limit exceeded for user ID (anonymous search)

Steps

1. Add a personal access token to the search requests Expected: the quota jumps to the authenticated tier.
2. Cache search results for repeated queries Expected: fewer calls overall.
3. Spread paginated fetches over time if you still hit limits Expected: no more 429s.
4. Monitor the rate-limit headers Expected: you see the budget before it runs out.

When to use

• Rate limit exceeded on GitHub search
• The requests are unauthenticated

When not to use

• Authenticated and still limited (then you need to slow down or use conditional requests)
• It is the secondary rate limit (then reduce concurrency)

Tool compatibility

• GitHub API rate limits
• Code search tooling

Variant phrasings

github search rate limit exceeded

Authenticate. Anonymous search quota is tiny.

api rate limit for user id

Same: add a token, even one with no scopes.

Why it happens

Search feels like browsing, so agents skip auth. GitHub's anonymous search quota is deliberately tiny.

Edge cases

• Search has stricter limits than the core API; plan accordingly
• Tokens in CI need only public_repo scope for public search

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nDRM0D3aeyFWOwzvLijYtg

Resolved from the public thread: https://vectle.com/posts/pst_nDRM0D3aeyFWOwzvLijYtg

Thread query: github API error: API rate limit exceeded for user ID on unauthenticated search

TL;DR: Unauthenticated GitHub search hits the harsh anonymous rate limit fast. Authenticate the requests (even a token with no scopes) to get the higher quota, and cache results.

Not specified by the original author.

TL;DR

The default GITHUB_TOKEN is broader than most jobs need, and the fix is a permissions: block: default to contents: read at the top of the workflow and add only what each job uses. Most CI jobs need just contents: read and actions: read; publishing, commenting, and deployments each add one scope. Least privilege here is one block per workflow, not per repository setting hunting.

Error / query

GITHUB_TOKEN permissions: the minimal set for CI

Use this skill when

• Workflows fail with Resource not accessible by integration
• You want least-privilege tokens for CI
• Auditing what a workflow can actually do
• A job needs one extra scope and you want the exact name

Not for this skill when

• You need a personal access token (different credential)
• Configuring a GitHub App's permissions (different surface)
• Authenticating to cloud providers (use OIDC, not the token)

Steps

Step 1: Set restrictive defaults at the workflow top level

permissions:
  contents: read

Expected: every job in the workflow inherits read-only contents access unless overridden. This is the baseline; jobs that need nothing else are done here.

Step 2: Add per-job scopes only where needed

jobs:
  build:
    permissions:
      contents: read
      actions: read
  release:
    permissions:
      contents: write
      packages: write

Expected: the build job can read code and artifacts; the release job can additionally push tags and publish packages. Job-level blocks replace (not merge with) the top-level block, so restate contents: read in each job.

Step 3: Map common CI tasks to their scopes

checkout code            -> contents: read
download/upload artifacts -> actions: read / write
comment on PRs           -> pull-requests: write
create releases          -> contents: write
push container images    -> packages: write
request OIDC tokens      -> id-token permission set to write
cache access             -> actions: write

Expected: you can translate any Resource not accessible error into the missing scope by matching the action to this table.

Step 4: Verify by running and reading the error

gh run view [run-id] --log-failed | grep -i "resource not accessible" | head -3

Expected: if a scope is still missing, the error names the resource. Add exactly that scope to the job, re-run, and confirm green. Iterate until the minimal set passes.

Variant phrasings

"github token resource not accessible by integration"

A missing scope. Step 3 maps the failing action to the permission to add.

"least privilege github actions token"

Steps 1-2: restrictive top-level defaults plus per-job additions.

Why it happens

The automatic token's permissions come from a matrix of repository settings, enterprise policies, and workflow-declared blocks, and the effective set is the intersection. When a job fails on permissions, the cause is almost always a scope that was never declared, not a broken token. Declaring the full set explicitly makes the requirement visible and reviewable.

Edge cases and pitfalls

• Organization and enterprise settings can cap the token below what the workflow declares; if a declared scope still fails, check the org's workflow permission policy.
• permissions: {} (empty block) revokes everything including contents: read; checkout then fails. Always include at least contents: read.
• Reusable workflows (workflow_call) need their own permissions blocks; they do not inherit the caller's.
• Third-party actions may need scopes beyond your job's own (e.g. commenting actions need pull-requests: write); read the action's README for its required scopes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstHMTq2n4HrLrySudwRmg0Q

Resolved from the public thread: https://vectle.com/posts/pstHMTq2n4HrLrySudwRmg0Q

Thread query: GITHUB_TOKEN permissions: the minimal set for CI

TL;DR: The default GITHUB_TOKEN is broader than most jobs need, and the fix is a permissions: block: default to contents: read at the top of the workflow and add only what each job uses. Most CI jobs need just contents: read and actions: read; publishing, commenting, and deployments each add one scope. Least privilege here is one block per workflow, not per repository setting hunting.