How to Set Up and Use the GitHub MCP Server — Complete Guide

Most developers interact with GitHub dozens of times a day. Check PR status. Create an issue. Review a diff. Push a branch. Each one is a tab switch, a mental context break, and a few minutes lost. The GitHub MCP server eliminates that friction by giving your AI coding assistant direct access to the GitHub API. You stay in your editor, describe what you need, and the assistant handles the API calls.

This is not a toy integration. The server exposes 20 tools that cover the core GitHub workflow: repositories, branches, issues, pull requests, file operations, code search, and workflow dispatch. It is maintained by Anthropic as part of the official MCP server collection, it ships as a single npm package, and it authenticates with a standard personal access token.

This guide covers everything you need to set it up, use it effectively, and avoid the common mistakes that trip people up.

What the GitHub MCP Server Exposes

The server provides 20 tools organized around the GitHub API surface that developers actually use daily. Here is what you get:

Repository operations: search_repositories, create_repository, fork_repository, get_file_contents, create_or_update_file, push_files. Your assistant can search across GitHub, read files from any public (or authorized private) repo, and push changes directly.

Branch management: create_branch, list_commits. Create feature branches and inspect commit history without touching the CLI.

Issue tracking: create_issue, list_issues, update_issue, add_issue_comment, search_issues. Full lifecycle management -- create, update, comment, and search across repositories.

Pull requests: create_pull_request, get_pull_request, list_pull_requests, merge_pull_request, get_pull_request_diff, get_pull_request_reviews, create_pull_request_review. This is the most powerful category. Your assistant can open PRs, read diffs, check existing reviews, and submit its own review comments.

Code search: search_code. Search across repositories using GitHub's code search API -- useful for finding usage patterns, deprecated API calls, or specific implementations across an organization.

At roughly 10,300 tokens for all tool definitions, the GitHub MCP server sits comfortably in the "worth the cost" category. That is about 5% of a 200K context window, and you get full GitHub API coverage in return.

Prerequisites

Before configuring anything, you need a GitHub Personal Access Token (PAT). There are two types, and the right choice matters.

Fine-grained tokens (recommended)

Go to GitHub Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens. These let you scope access to specific repositories and specific permissions. For most workflows, you need:

• Repository access: select the repositories you want the assistant to interact with (or "All repositories" if you prefer convenience over security)
• Permissions:
  • Contents: Read and write (for file operations and pushing)
  • Issues: Read and write (for issue management)
  • Pull requests: Read and write (for PR creation and review)
  • Metadata: Read-only (required for basic repo info)
  • Workflows: Read and write (only if you need to trigger GitHub Actions)

Classic tokens (simpler but broader)

If fine-grained tokens feel like too much configuration, classic tokens still work. Create one with the repo scope for full repository access, or add workflow if you need Actions support. The trade-off is that classic tokens grant access to all your repositories at once -- you cannot scope them to specific repos.

Either way, copy the token value. You will only see it once.

Setup: Claude Code

Claude Code reads MCP configuration from ~/.claude.json (global) or .claude/mcp.json (project-level). For a server you want available across all projects, use the global config.

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

Alternatively, use the CLI to add it directly:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Then set the environment variable in your shell profile or pass it inline. The CLI approach is faster, but editing the JSON gives you more control over the environment variables.

Setup: Cursor

Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global config):

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

After saving, reload Cursor (Cmd+Shift+P > "Reload Window"). Check the MCP panel in settings to confirm the server shows a green connected status.

Setup: VS Code (GitHub Copilot)

VS Code with GitHub Copilot supports MCP servers through settings.json. Add the server configuration under the mcp key:

{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
        }
      }
    }
  }
}

You can also add this to a workspace-level .vscode/settings.json to keep the configuration scoped to a specific project.

Real-World Workflows

Here is where the GitHub MCP server earns its keep. These are not hypothetical scenarios -- they are the daily workflows that become dramatically faster when your assistant has direct GitHub access.

Workflow 1: Review a PR and leave comments

You are asked to review a teammate's PR. Instead of opening GitHub in a browser, reading the diff, and writing comments by hand, you stay in your editor:

"Review PR #142 on our-org/api-service. Focus on error handling and any potential breaking changes. Leave review comments on specific lines that need attention."

The assistant calls get_pull_request_diff to read the changes, analyzes the code, and uses create_pull_request_review to submit a review with line-level comments. You get a structured code review in seconds that you can then refine or approve.

This is particularly powerful for large PRs. The assistant can process a 500-line diff faster than you can scroll through it, and it will catch patterns you might miss on a quick scan -- unchecked error returns, missing null guards, inconsistent naming.

Workflow 2: Create a feature branch and open a PR

You have finished implementing a feature locally and want to push it and open a PR. Rather than the usual git CLI dance:

"Create a branch called 'feat/user-preferences' from main on our-org/web-app, push the changes in src/lib/preferences.ts and src/components/settings-panel.tsx, and open a PR titled 'Add user preferences panel' with a description of the changes."

The assistant calls create_branch, then push_files to upload your changes, then create_pull_request to open the PR with your specified title and an auto-generated description based on the file contents. You get back the PR URL without ever leaving your editor.

Workflow 3: Triage issues by label

You maintain an open-source project and need to catch up on bug reports:

"Find all open issues labeled 'bug' in our-org/core-library. Summarize each one and suggest a priority order based on how many users are affected."

The assistant calls search_issues with the appropriate query filters, retrieves the issue bodies and comments, and presents a prioritized summary. For a project with 30 open bug reports, this turns a 45-minute triage session into a 5-minute review.

You can take it further: "For the top 3 priority bugs, add a comment acknowledging the report and asking for reproduction steps if they're missing." The assistant uses add_issue_comment to post on each issue.

Workflow 4: Search for deprecated API usage across your org

Your team is deprecating an internal API method and you need to find everywhere it is used:

"Search for all usages of 'legacyAuthMiddleware' across all repositories in our-org. Show me which files and repos still reference it."

The assistant calls search_code with the query scoped to your organization. GitHub's code search indexes all branches, so you get a comprehensive view of where the deprecated method still lives. This is the kind of task that would otherwise require cloning multiple repos or manually searching through the GitHub web UI.

Workflow 5: Automate repetitive issue creation

You are planning a sprint and need to create several issues from a spec:

"Create the following issues in our-org/mobile-app:

1. 'Implement offline mode for feed' - labeled 'feature', 'mobile'
2. 'Fix crash on image upload > 10MB' - labeled 'bug', 'critical'
3. 'Add analytics events for onboarding flow' - labeled 'feature', 'analytics' Assign all of them to @developer-username."

The assistant calls create_issue three times with the appropriate titles, labels, and assignees. Batch operations like this that would take 5 minutes in the GitHub UI happen in one conversational turn.

Workflow 6: Read and understand unfamiliar codebases

You are onboarding onto a new project or evaluating an open-source library:

"Read the main entry point and routing setup of vercel/next.js. Show me how the App Router initializes and which files are involved."

The assistant calls get_file_contents on multiple files, following imports and references to build a picture of how the code is structured. This is useful for exploring any public repository without cloning it locally. You can drill into specific modules, check how a function is implemented, or understand a project's architecture by asking the assistant to trace through the code.

This also works well for competitive analysis. If you want to understand how a similar product handles a feature, the assistant can pull the relevant source files and explain the approach.

Workflow 7: Monitor and manage workflows

If you use GitHub Actions, the server's workflow tools let you trigger and check on CI/CD runs:

"Trigger the 'deploy-staging' workflow on our-org/web-app's develop branch. Then check the status of the last 5 workflow runs."

The assistant dispatches the workflow and can follow up by checking run status. This is particularly useful during active development when you are iterating on deployment configurations and need rapid feedback on whether a workflow succeeded.

Token Budget Impact

At 20 tools and roughly 10,300 tokens, the GitHub MCP server is one of the more efficient servers available. To put that in perspective:

• On Claude's 200K context window, it consumes about 5% of your available space
• You can comfortably run it alongside 3-4 other MCP servers without token pressure
• Compare this to heavier servers like Firebase MCP (50+ tools, ~25K tokens) or a fully-loaded GitLab community MCP (69+ tools)

If you are running a lean stack -- GitHub MCP plus one or two others -- your total MCP overhead stays under 15% of the context window, which is the sweet spot for balancing tool availability against space for your actual code and conversation.

Common Gotchas

Token scope mismatch

The most common setup failure is a token that does not have the right permissions. If the assistant can read issues but cannot create them, your token is missing write access. If it cannot see private repos, the token was not granted access to those repositories.

Fix: go back to your token settings and check the permissions. For fine-grained tokens, make sure each permission category (Issues, Pull requests, Contents) has "Read and write" access.

GitHub API rate limits

GitHub enforces rate limits on API calls. For authenticated requests (which is what the MCP server makes), the limit is 5,000 requests per hour for REST API and 30 requests per minute for code search. Under normal use, you will not hit these limits. But if you ask the assistant to do something like "search every repo in our org and list all TODO comments," you could exhaust your quota quickly.

Fix: be specific with your queries. Searching one repo is one API call. Searching an entire organization is many. If you get rate-limited, wait an hour or use a different token.

Organization access restrictions

Some GitHub organizations require tokens to be approved before they can access org resources. Even if your token has the right scopes, the org admin may need to approve it.

Fix: check your organization's settings under "Personal access tokens" and request approval for your token. For fine-grained tokens, you may need to select the organization as the resource owner when creating the token.

Large file operations

The push_files tool works through the GitHub API, not through git. It creates commits via the API, which means there are size limits. Individual files over 100MB will fail, and pushing many files at once can be slow.

Fix: for large-scale file operations, use git directly. The GitHub MCP server is best for targeted file changes -- updating a config file, adding a new module, fixing a specific file. It is not a replacement for git push on a 200-file commit.

Stale npx cache

The npx -y command caches packages locally. If the GitHub MCP server publishes an update with bug fixes or new tools, you might still be running the cached older version. This can cause confusion when a documented feature does not seem to work.

Fix: clear the npx cache occasionally with npx clear-npx-cache, or run npx -y @modelcontextprotocol/server-github@latest to force the latest version.

API responses exceeding context limits

Some GitHub API responses are large. Listing all issues on a popular repository or fetching the diff of a massive PR can return more data than the context window can comfortably hold. The assistant may truncate results silently.

Fix: scope your requests. Instead of "list all issues," ask for "the 10 most recent open issues labeled 'bug'." Instead of reviewing a 3,000-line PR in one go, ask the assistant to review specific files within the PR.

Security Considerations

Your GitHub PAT gives the MCP server -- and by extension, the AI model -- access to your repositories. Treat this with the same care you would give any credential.

Use the least privilege necessary. Fine-grained tokens exist for this reason. If your workflow only involves one repository, scope the token to that repo. If you only need to read code and create issues, do not grant write access to repository contents.

Never commit tokens to version control. If your mcp.json or claude.json contains a real token, add it to .gitignore. Use placeholder values in committed configs and document which tokens team members need to generate.

Rotate tokens regularly. GitHub lets you set expiration dates on fine-grained tokens. A 90-day expiration is a reasonable default. When the token expires, generate a new one and update your config.

Audit access periodically. GitHub shows which applications and tokens have accessed your account and repositories. Check Settings > Applications > Authorized OAuth Apps and Settings > Developer Settings > Personal Access Tokens to review what has access.

Be thoughtful about what you ask the assistant to do. The assistant can push code, merge PRs, and modify issues. In a production repository, a careless instruction like "merge all open PRs" could have real consequences. Review the assistant's proposed actions before confirming destructive operations.

Pairing with Other Servers

The GitHub MCP server works well alongside:

• Context7 MCP: when the assistant creates a PR or writes code, Context7 ensures it uses the correct, up-to-date API patterns for whatever framework you are working with.
• Playwright MCP: the assistant can create a branch, push changes, and then verify the result by navigating a browser to your preview deployment.
• Sentry MCP: debug a production error by pulling the stack trace from Sentry, finding the relevant code via GitHub, and opening a PR with the fix -- all in one conversation.
• Linear or Jira MCP: close the loop between project management and code. The assistant can read a ticket, create a branch named after the ticket, implement the change, open a PR, and update the ticket status.

Getting Started

If you have not used MCP servers before, the GitHub MCP server is one of the best places to start. The setup takes under two minutes, the token cost is low, and the payoff is immediate -- every developer interacts with GitHub daily.

1. Generate a fine-grained PAT from GitHub Settings
2. Add the config block to your editor (use the examples above for Claude Code, Cursor, or VS Code)
3. Reload your editor and test with a simple request: "List my open PRs"

For a pre-configured setup that includes the GitHub MCP server alongside complementary tools for your workflow, check out the curated stacks on stackmcp.dev. The Backend Developer, Fullstack Web, and Open Source Maintainer stacks all include GitHub MCP with configurations ready for your preferred AI client. You can also view the full server details at stackmcp.dev/servers/github-mcp.