GitHub MCP Server for Claude Code: Setup, PAT Scopes, and Read-Only Mode Explained

Connecting GitHub to Claude Code via MCP opens up powerful possibilities—from reading repositories and creating issues to reviewing pull requests. But getting the setup right takes attention to detail. This guide walks you through it, from creating a Personal Access Token to running in read-only mode for safety.

Why connect GitHub to Claude Code?

Claude Code can help you navigate repositories, understand codebases, and even create or update files—but only if you give it the right permissions and configuration. MCP (Model Context Protocol) acts as the bridge, allowing Claude to interact with GitHub repositories through a standardised interface.

Once set up, you can:

Browse repository files and understand code structure
Create and manage issues and pull requests
Review changes without needing to leave your editor
Run all of this in read-only mode for safety if you prefer

The key challenge is configuring it correctly. A single error in your setup—a malformed JSON file, wrong token scopes, or incorrect environment variable—leaves you staring at authentication errors with no clear diagnosis.

Understanding local vs remote MCP servers

Before you start, you need to decide how to run the GitHub MCP server. This choice affects your configuration, security, and how Claude accesses GitHub.

Local MCP servers

A local server runs on your machine as a Node.js process. It uses the stdio transport, meaning Claude communicates with it directly through standard input/output. Local servers have direct access to your filesystem and environment variables.

When to use local: You want full control over the server, prefer not to send requests over the network, or need tight integration with your development environment.

Configuration: Stored in a JSON config file, typically at ~/.claude.json or .mcp.json in your project directory.

Remote MCP servers

A remote server is hosted elsewhere—either by a vendor or on your own infrastructure. Claude communicates with it via HTTP, sending requests and receiving responses over the network.

When to use remote: You want GitHub's official hosting, don't want to manage server processes, or need to share the same server configuration across a team.

Configuration: Simpler; you just provide the server URL and credentials through Claude's UI or config file.

First time? Start with remote if GitHub offers it. Less to troubleshoot. Migrate to local later if you need more control.

Step 1: Create a GitHub Personal Access Token (PAT)

Claude needs permission to access your GitHub account. That permission comes through a Personal Access Token.

Fine-grained vs classic tokens

GitHub offers two token types. Fine-grained tokens are newer and more secure because they give you granular control over exactly what Claude can do. Classic tokens are broader.

GitHub recommends fine-grained tokens. With fine-grained tokens, you can grant "read" or "read and write" access to specific resource types—repositories, issues, pull requests—independently. This follows the principle of least privilege: Claude gets only the permissions it actually needs.

Creating a fine-grained token

Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens. Click "Generate new token".

Fill in the details:

Token name: Something descriptive, like "Claude Code MCP"
Expiration: 90 days is a sensible default. Shorter is more secure.
Resource owner: Your account (or your organisation if you have appropriate permissions)
Repository access: "Only select repositories" (choose which ones Claude needs), or "All repositories" if you want Claude to access any repo you own

Minimum permissions for GitHub MCP

Permissions depend on what you want Claude to do. Here's the principle: grant only what you need.

Read repository contents: Contents → Read-only
Read issues and pull requests: Issues → Read-only; Pull requests → Read-only
Create issues: Issues → Read and write
Approve pull requests: Pull requests → Read and write
Read organisation info: Members → Read-only (if working with org repos)

Start minimal. If Claude tells you it lacks permission, add the next scope and regenerate.

Copy and store the token safely

After creation, GitHub shows your token once. Copy it immediately. If you lose it, you must delete it and create a new one.

Do not hardcode tokens in public repositories, version control, or chat windows. Treat them like passwords.

Step 2: Install and configure the GitHub MCP server

Option A: Local setup (npm)

Install the official GitHub MCP server via npm:

npm install -g @modelcontextprotocol/server-github

Then configure it. On macOS/Linux, edit (or create) ~/.claude.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN_HERE"
      }
    }
  }
}

On Windows, the configuration is slightly different. CMD needs an extra wrapper:

{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Replace ghp_YOUR_TOKEN_HERE with your actual token.

JSON is strict. One missing comma or mismatched bracket silently breaks all servers. Validate your JSON before restarting Claude: use cat ~/.claude.json | python3 -m json.tool or an online JSON validator.

Option B: Remote setup

If you prefer not to manage the server process, use GitHub's hosted version. In Claude Code, click the "+" button, navigate to Connectors → Manage Connectors, and either select GitHub from the library or add a custom server URL.

You'll paste your token when prompted.

Step 3: Enable read-only mode (recommended)

Read-only mode prevents Claude from modifying anything on GitHub—no new issues, no commits, no deletions. It's perfect for code review, exploration, and learning.

Enabling read-only mode

For local servers, add the environment variable to your .claude.json config:

"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN_HERE",
  "GITHUB_READ_ONLY": "1"
}

Alternatively, pass the flag directly when running the server:

npx @modelcontextprotocol/server-github --read-only

For remote servers, if you're running your own, add the header X-MCP-Readonly: true to your requests. If using GitHub's hosted version, check their documentation for read-only configuration.

Once read-only mode is on, Claude will only have access to read tools. If it tries to create an issue, you'll get a permission error. The mode acts as a hard safety filter, overriding any other configuration.

Common errors and how to fix them

Server doesn't appear in Claude Code

Cause: Usually a broken JSON config file. JSON silently fails.

Fix: Validate your .claude.json file. Use cat ~/.claude.json | python3 -m json.tool or an online validator. Fix any syntax errors, then restart Claude.

"Authentication failed: Bad credentials"

Cause: Your PAT is incorrect, expired, or has insufficient scopes.

Fix:

Copy a fresh token from GitHub. Paste it directly into your config (watch for extra whitespace or newlines).
Check that your token hasn't expired. GitHub shows expiration in Settings → Personal access tokens.
If it's near expiration, delete it and create a new one.
Verify your token has at least repo scope (for classic tokens) or the equivalent fine-grained permissions.

"Command not found" when Claude starts

Cause: Claude can't find the npx command. This happens because the GUI app (Claude Desktop or Cursor) has a different environment than your terminal.

Fix:

Ensure Node.js is installed globally: which node should return a path.
Use absolute paths in your config if possible. Instead of "npx", use the full path (e.g., "/usr/local/bin/npx" or "C:\\Program Files\\nodejs\\npm.cmd" on Windows).
Restart Claude after making changes.

"Server reconnection failed" after authentication

Cause: Temporary connection issue or OAuth token expiration.

Fix: Restart Claude Code. If this happens repeatedly, delete and re-add the server with a fresh token.

Security recommendations

Use fine-grained tokens. They're newer and give you precise control over permissions.
Set an expiration. 90 days is a good balance. Shorter is more secure.
Rotate regularly. Delete old tokens and create new ones every few months.
Start with read-only. Enable it by default. Only add write permissions if Claude actually needs them.
Limit repository access. Use "Only select repositories" instead of giving Claude access to every repo you own.
Never hardcode tokens in version control. Use environment variables or separate config files that you don't commit.
Audit your tokens. Visit GitHub Settings → Developer settings → Personal access tokens and review which ones are active. Delete anything you're not using.

Frequently asked questions

Can I use the same token on multiple machines?

Yes. A token is tied to your GitHub account, not a specific machine. You can use the same token on your laptop, desktop, and server. That said, if one machine is compromised, an attacker has access to all machines using that token. For high-security setups, consider different tokens per machine or per environment (dev/staging/production).

What if I want Claude to modify repositories?

Create a second token with write permissions (e.g., Contents → Read and write, Pull requests → Read and write) and use that for tasks where you need modifications. Keep your read-only token for browsing and exploration. This reduces the blast radius if the read-write token leaks.

Is it safe to use MCP with closed-source code?

Mostly yes, with caveats. Your code stays in your repository; Claude reads it and processes it server-side (by Anthropic). Check Anthropic's privacy policy and your company's data governance rules. If your code is highly sensitive, consider running Claude locally or in an air-gapped environment. For private repositories on GitHub, the token grants access only to repos you've explicitly authorised.

Can I use GitHub's official MCP server or should I build my own?

Use GitHub's official server. It's maintained, tested, and regularly updated with new features. Building your own is only necessary if you need custom logic or integration with internal systems that GitHub's server doesn't support.

What happens if my token expires?

Claude will get authentication errors when it tries to use GitHub. Check the error message—it usually tells you the token is invalid or expired. Generate a new token, update your config, and restart Claude.