GitHub MCP Server Setup for Codex & Claude | Complete 2026 Guide

GitHub MCP Server Setup and Configuration Guide

The official GitHub Model Context Protocol (MCP) server enables AI agents—including Claude Desktop, Cursor, Windsurf, and OpenAI Codex CLI—to interact directly with your GitHub repositories. Once configured, your AI assistant can review code, create pull requests, search across codebases, triage issues, and automate complex workflows using standardized tool calls.

This guide walks you through generating a fine-grained Personal Access Token (PAT), configuring your client of choice, and troubleshooting permissions and SAML SSO hurdles.

Prerequisites

• ▸An active GitHub account.
• ▸A GitHub Personal Access Token (PAT) with repository permissions.
• ▸Node.js 18+ installed on your system (verify with node -v).

Step 1: Create a Fine-Grained Personal Access Token

We strongly recommend using Fine-Grained Personal Access Tokens instead of classic tokens to adhere to the principle of least privilege.

1. ▸Navigate to GitHub Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens (opens in a new tab).
2. ▸Click Generate new token.
3. ▸Fill in the token details:
   • ▸Token name: mcp-github-server
   • ▸Expiration: Choose 30, 60, or 90 days (never select "No expiration" in enterprise environments).
   • ▸Repository access: Choose Only select repositories and pick the repositories your agent will work on.
4. ▸Set Repository Permissions:
   • ▸Contents: Read and write (for reading code, creating commits, and creating branches)
   • ▸Pull requests: Read and write (for drafting and reviewing PRs)
   • ▸Issues: Read and write (for listing and creating issues)
   • ▸Metadata: Read-only (selected automatically)
5. ▸Click Generate token and copy the token string (github_pat_...) immediately.

Step 2: Configure Your AI Client

Select your host environment below to copy the exact configuration template.

Claude Desktop (claude_desktop_config.json)

File path:

• ▸macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• ▸Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor IDE (~/.cursor/mcp.json)

File path:

• ▸macOS/Linux: ~/.cursor/mcp.json
• ▸Windows: %USERPROFILE%\.cursor\mcp.json

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

OpenAI Codex CLI (~/.codex/config.toml)

File path:

• ▸macOS/Linux: ~/.codex/config.toml
• ▸Windows: %USERPROFILE%\.codex\config.toml

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

  [mcp_servers.github.env]
  GITHUB_PERSONAL_ACCESS_TOKEN = "github_pat_your_token_here"

Or add it in one terminal command:

codex mcp add --name github --command "npx -y @modelcontextprotocol/server-github" --env GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_your_token_here

Windsurf / Cascade (~/.codeium/windsurf/mcp_config.json)

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

Step 3: Verify the Connection

1. ▸Save your configuration file and restart your AI client (or run codex mcp restart github in Codex CLI).
2. ▸Open a chat session with your AI agent and prompt:

   "Use the GitHub tool to search for open pull requests in my repository <owner>/<repo>."

3. ▸The client will trigger the search_repositories or list_pull_requests tool. If prompted, confirm execution.

Available GitHub Tools Reference

The GitHub MCP server provides 20+ specialized tools:

Troubleshooting Common Issues

1. 403 Forbidden / SAML SSO Enforcement

• ▸Symptom: API requests return 403 Resource not accessible by personal access token or SAML error.
• ▸Fix: If your organization uses Single Sign-On (SAML SSO), you must authorize your token. Go to Personal access tokens in GitHub, find your token, click Configure SSO, and click Authorize next to your organization name.

2. 404 Not Found When Querying Repositories

• ▸Symptom: Agent reports repository does not exist.
• ▸Fix: Verify you provided both the repository owner and name in format <owner>/<repo>. Also ensure the fine-grained PAT includes access to that specific repository under "Selected Repositories".

3. Rate Limit Exceeded

• ▸Symptom: 403 API rate limit exceeded.
• ▸Fix: Personal Access Tokens are granted 5,000 requests per hour. For high-frequency CI/CD agents, consider authenticating via a GitHub App instead of a PAT.

Interactive Links & Tools

• ▸GitHub Server Detail & Tools List
• ▸Customize GitHub in Visual Config Generator
• ▸Compare GitHub vs Git MCP Server
• ▸Client Compatibility Matrix