Ian Homer's dev blog

Connecting GitHub with Claude Code through MCP

Published on by

I've been exploring ways to give Claude Code more context about my projects, and the GitHub MCP server caught my attention. Setting it up turned out to be straightforward.

The basic setup

The GitHub MCP server connects Claude Code directly to GitHub's API through the Model Context Protocol. This means Claude can read repositories, browse issues, and understand project structure without you manually copying content into conversations.

Getting started requires just a few steps:

claude mcp add -s user github --transport http https://api.githubcopilot.com/mcp

This command adds the GitHub server to your Claude Code configuration. The -s user flag installs it for your user account rather than globally.

Authentication with personal access tokens

You'll need a GitHub personal access token for authentication. I created a classic token.

You can start with no scopes selected. This gives read-only access to public repositories, which is perfect for initial exploration. You can always expand permissions later as your needs grow.

Once you have your token, add it to your Claude configuration file at ~/.claude.json:

"github": {
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp",
  "headers": {
    "Authorization": "Bearer ${GITHUB_READ_ONLY_PAT}"
  }
}

Environment variable management

Rather than hardcoding the token in the JSON file, I used an environment variable GITHUB_READ_ONLY_PAT. This keeps sensitive credentials out of configuration files.

I manage environment variables with direnv, which automatically loads project-specific environment variables when you enter a directory. Adding a .envrc file with:

export GITHUB_READ_ONLY_PAT="ghp_your_token_here"

This approach separates configuration from secrets, making it safer to version control your Claude settings.

Why start with read-only

Beginning with minimal permissions serves two purposes. First, it limits potential damage if something goes wrong. Second, it forces you to understand what the integration actually does before granting broader access.

Read-only access to public repositories lets you explore repositories, read documentation, and browse code structure. This covers most exploratory use cases without risking accidental modifications.

What this enables

With the GitHub MCP server connected, Claude Code can browse repository contents, understand project structure, and reference specific files or documentation. This eliminates the manual work of copying code snippets or explaining project context in every conversation.

The integration feels natural - Claude can suggest changes based on actual codebase patterns rather than generic examples. It understands your existing conventions and can reference specific files when discussing improvements.

Example: Fixing pipeline failures

When you say "fix the pipeline failure on this branch", Claude can examine the recent workflow run, view the details of a recent failure, check recent commits, identify what has changed and have go at fixing it. It might spot that a new dependency wasn't added to the CI configuration or that a test is failing due to an environment variable change.

To make this particular exercise even more effective, the following prompt helped for me:

When troubleshooting pipeline failures or issues on a feature branch, always examine the diff between the current branch and main to understand what changes may have caused the problem. Use git diff main...HEAD or similar commands to identify recent modifications that could be related to the failure. This context is crucial for accurate diagnosis.

Use this diff context to guide your troubleshooting rather than just examining error logs in isolation.

Oddly (and this is probably model specific), it kept trying to fix the issue from raw principles without actually looking at recent changes, where often an important clue lies. I ended up adding this to my master prompt.

Configuration references

The GitHub documentation provides comprehensive setup guidance, particularly around tool configuration. The Claude Code MCP documentation covers the broader context of how MCP servers integrate with Claude.

Categories