From 4cec9f3cf750ebb5e206a230ffedd64e6cae7ca7 Mon Sep 17 00:00:00 2001 From: syf2211 Date: Tue, 11 Aug 2026 00:18:35 +0000 Subject: [PATCH] docs: add minimum PAT permissions for default toolsets Document the smallest fine-grained and classic PAT permissions needed for the default github-mcp-server toolsets, and link to the fine-grained token creation UI. Fixes #2963 --- docs/installation-guides/README.md | 13 ++++++++++++- docs/scope-filtering.md | 15 +++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/installation-guides/README.md b/docs/installation-guides/README.md index 46581aa77e..94f89b62d5 100644 --- a/docs/installation-guides/README.md +++ b/docs/installation-guides/README.md @@ -78,7 +78,18 @@ The GitHub MCP Server can be installed using several methods. **Docker is the mo ## General Prerequisites All installations with Personal Access Tokens (PAT) require: -- **GitHub Personal Access Token (PAT)**: [Create one here](https://github.com/settings/personal-access-tokens/new) +- **GitHub Personal Access Token (PAT)**: [Create a fine-grained token](https://github.com/settings/personal-access-tokens/new) (recommended) or a [classic token](https://github.com/settings/tokens/new) + +### Minimum token permissions + +Use the smallest permission set that matches the toolsets you enable. The server starts with the **default** toolsets (`context`, `repos`, `issues`, `pull_requests`, `users`, `copilot`) unless you pass `--toolsets` or `GITHUB_TOOLSETS`. + +| Token type | Minimum for default toolsets | Notes | +|------------|------------------------------|-------| +| **Fine-grained PAT** (recommended) | Repository access limited to the repos you need, with **Contents**, **Issues**, and **Pull requests** set to *Read and write* (Metadata: *Read* is added automatically) | Scopes are enforced by the GitHub API; the server cannot auto-hide tools for fine-grained tokens. See [PAT scope filtering](../scope-filtering.md#classic-vs-fine-grained-personal-access-tokens). | +| **Classic PAT** | `repo` (add `read:org` for org team/issue-type tools such as `get_teams`, `list_issue_types`) | Covers the default read/write repository, issue, and pull request tools. Add scopes only when enabling extra toolsets—for example `notifications` for the notifications toolset or `project` for projects. See the [scope filtering guide](../scope-filtering.md) and per-tool scope tables in the [README](../../README.md#tools). | + +**Read-only deployments:** pass `--read-only` (or set `GITHUB_READ_ONLY=1`). For classic PATs, `public_repo` is enough for public repositories; private repository reads still need `repo`. Optional (depending on installation method): - **Docker** (for Docker-based installations): [Download Docker](https://www.docker.com/) diff --git a/docs/scope-filtering.md b/docs/scope-filtering.md index f29d631ca1..510419a365 100644 --- a/docs/scope-filtering.md +++ b/docs/scope-filtering.md @@ -82,6 +82,21 @@ WARN: failed to fetch token scopes, continuing without scope filtering **Fine-grained PATs** (`github_pat_` prefix) use a different permission model based on repository access and specific permissions rather than OAuth scopes. They don't return the `X-OAuth-Scopes` header, so scope filtering is skipped. All tools will be available, but the GitHub API will still enforce permissions at the API level—you'll get errors if you try to use tools your token doesn't have permission for. +### Minimum permissions (default toolsets) + +When you run the server without custom `--toolsets`, the default set (`context`, `repos`, `issues`, `pull_requests`, `users`, `copilot`) needs repository read/write access for core issue/PR/file workflows: + +| Token type | Grant | +|------------|-------| +| Fine-grained PAT | Limit repository access to the repos you need. Under **Repository permissions**, enable **Contents**, **Issues**, and **Pull requests** (Read and write). Org-scoped tools (`get_teams`, `list_issue_types`, …) may also need **Organization → Members** (Read). | +| Classic PAT | `repo` (add `read:org` if you use org team or issue-type tools in the default toolsets) | + +Enable additional classic scopes only for non-default toolsets you turn on (for example `notifications`, `project`, `gist`). Each tool's required scopes are listed in the [README tool tables](../README.md#tools). + +For read-only mode (`--read-only` / `GITHUB_READ_ONLY=1`), use the smallest read access that matches your repositories: `public_repo` for public repos only, or `repo` when private repositories must be readable. + +See also the [installation prerequisites](./installation-guides/README.md#minimum-token-permissions) for links to the token-creation UI. + ## GitHub App and Server-to-Server Tokens **GitHub App installation tokens** (`ghs_` prefix) and other server-to-server tokens use a permission model based on the app's installation permissions rather than OAuth scopes. These tokens don't return the `X-OAuth-Scopes` header, so scope filtering is skipped. The GitHub API enforces permissions based on the app's configuration.