GitHub

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

Give agents repository context with the runnable GitHub example. Its three tools use Node's built-in fetch and GitHub's REST API. They do not modify files, comment, or merge pull requests.

Start from the GitHub MCP server template for setup instructions and a runnable workflow.

Configure access

Create a fine-grained token scoped to the repositories you want to expose. Grant Pull requests: read for PR tools and Contents: read for file reads, following GitHub's pull request and contents documentation.

GITHUB_TOKEN=your-github-token
MCP_API_KEY=your-separate-client-secret

MCP clients send x-api-key on every request. The server sends only the provider token to https://api.github.com as a Bearer token, with API version 2026-03-10. It does not follow redirects or external download URLs. All clients share the token's repository access; owner and repo are selectors, not per-user authorization.

Available tools

Call list-pull-requests with:

{
  "owner": "basementstudio",
  "repo": "xmcp",
  "state": "open",
  "limit": 20
}

The JSON text result contains pullRequests and nextPage. State defaults to open; closed and all are also supported. limit accepts 1–50 and defaults to 20. Pass a non-null nextPage as page with the other arguments unchanged. Pagination is explicit.

Read PR details and files

Use get-pull-request with owner, repo, and a number from the list. It returns metadata and description, not review comments, checks, or diffs. mergeable: null is preserved when GitHub has not finished determining mergeability.

Call read-repository-file with:

{
  "owner": "basementstudio",
  "repo": "xmcp",
  "path": "README.md",
  "ref": "main"
}

The response includes the path, file blob SHA, GitHub URL, and decoded content. Omit ref for the default branch or use a commit SHA for a stable snapshot. For a fork PR, select the repository from head.repo.full_name and use head.sha; deleted forks may have no repository metadata.

The example limits files to 100,000 bytes and rejects directories, submodules, binary data, and invalid UTF-8. It does not traverse the repository or retrieve download URLs automatically. GitHub may resolve in-repository symlinks to their target files.

Errors and testing

Provider failures return tool errors with status codes, without raw error bodies. Numeric Retry-After values are included for HTTP 403/429 when supplied. Requests time out after 30 seconds with no automatic retries. Use the current repository owner/name after a rename, because redirects are disabled.

Follow the README for Node 22/pnpm setup and runnable requests. Tests mock provider calls and cover both MCP 2025-03-26 and 2026-07-28. Live repository permissions require your own token.