GitHub MCP Setup

Configure the GitHub MCP server to access GitHub repositories, issues, pull requests, and workflows directly from Claude Code using secure token management via 1Password.

IMPORTANT: This skill uses 1Password CLI to securely fetch GitHub tokens. Tokens are NEVER hardcoded.

When to Use This Skill

Use this skill when:

• Setting up MCP server integration for GitHub
• Working with GitHub repositories, issues, or pull requests
• Automating GitHub workflows
• Troubleshooting GitHub MCP connection
• Reauthenticating with different GitHub token
• Configuring organization-specific tokens per repository

Configuration Scopes

GitHub MCP supports two configuration scopes:

Global Configuration (User-wide)

• Config file: ~/.claude.json
• Use when: Single GitHub account across all projects
• Token: Shared across all repositories
• Command: bun .claude/skills/github-mcp/configure-mcp.ts --global

Local Configuration (Project-specific)

• Config file: .claude/mcp.json (gitignored)
• Use when: Different GitHub organizations or accounts per repository
• Token: Specific to this project only
• Command: bun .claude/skills/github-mcp/configure-mcp.ts --local
• Auto-detection: Script uses local config if .env file exists

Recommended approach: Use local configuration when working with organization-specific tokens.

Automated Setup Workflow

When this skill is invoked, follow these steps in order:

Step 1: Check if MCP Tools Are Available

Attempt to use a GitHub MCP tool:

text
1Use: mcp__github__search_repositories
2Input: { "query": "test" }

• If successful: MCP is ready. Skip to usage section.
• If fails with "No such tool available": Continue to Step 2.

Step 2: Check if MCP Server Is Configured

Run check to see server status:

bash
1claude mcp list

Possible outcomes:

A) Server not listed:

• Run configuration script: bun .claude/skills/github-mcp/configure-mcp.ts
• Script will auto-detect scope (local if .env exists, otherwise global)
• Script will prompt for 1Password authentication (30 second timeout)
• Instruct user: "The GitHub MCP server has been configured. Please restart Claude Code with claude -c to continue this conversation."
• STOP HERE - Wait for user to restart and continue

B) Server listed with "✓ Connected":

• MCP should be available but tools aren't loading
• Instruct user: "Please restart Claude Code with claude -c to reload MCP servers."
• STOP HERE - Wait for user to restart and continue

C) Server connected but using wrong/expired token:

• User reports authentication errors or wrong repository access
• Run reauthentication: bun .claude/skills/github-mcp/configure-mcp.ts --reauth
• Follow reauthentication workflow (see Reauthentication section below)
• STOP HERE - Wait for user to complete reauth flow

Step 3: Add Global Allow Patterns (Optional)

To avoid permission prompts for GitHub MCP tools:

bash
1bun .claude/skills/github-mcp/configure-mcp.ts --allow-patterns

This adds mcp__github__* to ~/.claude/settings.json allowed tools.

Step 4: Verify Connection

After user restarts, repeat Step 1 to verify tools are now available.

Prerequisites

Required: Bun Runtime

Check if installed:

bash
1which bun

If not installed:

bash
1curl -fsSL https://bun.sh/install | bash

Required: 1Password CLI

Check if installed:

bash
1which op

If not installed:

bash
1brew install 1password-cli

Required: .env File with 1Password Reference

The .env file must contain:

bash
1GITHUB_TOKEN=op://Private/GitHub.com/GITHUB_TOKEN

Format: op://vault/item/field

• vault: 1Password vault name (e.g., "Private")
• item: Item name in vault (e.g., "GitHub.com")
• field: Field name (e.g., "GITHUB_TOKEN")

1Password Authentication

When running the script, 1Password will prompt for authentication:

• Timeout: 30 seconds
• Action required: Approve 1Password access request
• Failure: Script exits with timeout error

Available MCP Tools

Once connected, you'll have access to GitHub MCP tools including:

Repository Operations:

• mcp__github__search_repositories - Search GitHub repositories
• mcp__github__get_repository - Get repository details
• mcp__github__list_commits - List repository commits
• mcp__github__get_file_contents - Read file contents

Issue Operations:

• mcp__github__search_issues - Search issues across repositories
• mcp__github__create_issue - Create new issue
• mcp__github__update_issue - Update issue details
• mcp__github__list_issues - List repository issues

Pull Request Operations:

• mcp__github__search_pull_requests - Search pull requests
• mcp__github__create_pull_request - Create new PR
• mcp__github__list_pull_requests - List repository PRs
• mcp__github__merge_pull_request - Merge a PR

Workflow Operations:

• mcp__github__list_workflows - List GitHub Actions workflows
• mcp__github__get_workflow_run - Get workflow run details
• mcp__github__trigger_workflow - Trigger workflow dispatch

Usage Examples

Search Your Pull Requests (Recommended):

typescript
1Use: mcp__github__search_pull_requests
2Input: { "query": "is:open is:pr author:@me" }

Why use author:@me?

• Searches content created by the authenticated user
• Avoids permission errors when searching specific usernames
• Works across all repositories you have access to

Search Repositories:

typescript
1Use: mcp__github__search_repositories
2Input: { "query": "language:typescript stars:>1000" }

Search Your Issues:

typescript
1Use: mcp__github__search_issues
2Input: { "query": "is:open is:issue author:@me" }

Create Issue:

typescript
1Use: mcp__github__create_issue
2Input: {
3  "owner": "northbridge-security",
4  "repo": "ai-toolkit",
5  "title": "Bug: Fix data pipeline timeout",
6  "body": "Pipeline times out after 5 minutes..."
7}

List Pull Requests (Specific Repository):

typescript
1Use: mcp__github__list_pull_requests
2Input: {
3  "owner": "northbridge-security",
4  "repo": "ai-toolkit",
5  "state": "open"
6}

Note: Repository-specific operations (list, create, update) require exact owner/repo names. If repository names are unclear or custom git remotes are used, use search APIs with author:@me first to discover accessible repositories.

Best Practices

Use Search APIs for Discovery

Recommended pattern:

1. Use search APIs with author:@me to discover content
2. Extract exact owner/repo names from results
3. Use repository-specific APIs for detailed operations

Example workflow:

typescript
1// Step 1: Find your repositories
2Use: mcp__github__search_repositories
3Input: { "query": "user:@me" }
4
5// Step 2: Use exact names from results
6Use: mcp__github__list_pull_requests
7Input: {
8  "owner": "username",
9  "repo": "my-repo",
10  "state": "open"
11}

Common Search Patterns

Your open PRs across all repos:

text
1is:open is:pr author:@me

Your issues assigned to you:

text
1is:open is:issue assignee:@me

PRs you reviewed:

text
1is:pr reviewed-by:@me

Recent activity:

text
1is:pr author:@me updated:>2025-01-01

Avoiding Permission Errors

Don't use: user:my-username (may fail with 422 validation error)

Use instead: author:@me (always works for authenticated user)

Why: GitHub's search API has different permission models for username searches vs authenticated user searches. Using @me ensures the token's permissions are correctly applied.

Reauthentication

If you need to switch tokens or reauthenticate:

Run reauthentication script:

bash
1bun .claude/skills/github-mcp/configure-mcp.ts --reauth

This will:

1. Remove existing MCP server configuration
2. Fetch fresh token from 1Password (30 second timeout)
3. Reconfigure server with new token

After running reauthentication:

1. Restart Claude Code with claude -c
2. GitHub MCP tools should now use new token

Use cases:

• Token expired or rotated
• Need to switch between GitHub accounts
• Repository access permissions changed
• Testing with different token scopes

Troubleshooting

1Password CLI Not Found

Error: 1Password CLI (op) is not installed

Solution:

bash
1brew install 1password-cli

Verify installation:

bash
1op --version

1Password Authentication Timeout

Error: Timeout: 1Password authentication not completed within 30 seconds

Causes:

• User didn't approve 1Password prompt in time
• 1Password app not running
• 1Password CLI not authenticated

Solutions:

1. Ensure 1Password app is running

2. Authenticate 1Password CLI:

   bash
   1op account list
   2op signin

3. Run configure script again

4. Approve 1Password prompt within 30 seconds

GITHUB_TOKEN Not Found in .env

Error: GITHUB_TOKEN not found in .env file

Solution:

Create or update .env file in project root:

bash
1GITHUB_TOKEN=op://Private/GitHub.com/GITHUB_TOKEN

Verify 1Password reference is correct:

bash
1op read op://Private/GitHub.com/GITHUB_TOKEN

Invalid 1Password Reference

Error: 1Password CLI failed: [error message]

Solutions:

1. Check vault name: Ensure vault exists in 1Password

   bash
   1op vault list

2. Check item name: Verify item exists in vault

   bash
   1op item list --vault Private

3. Check field name: Confirm field exists in item

   bash
   1op item get "GitHub.com" --vault Private

4. Test reference directly:

   bash
   1op read op://Private/GitHub.com/GITHUB_TOKEN

Tools Not Appearing After Configuration

Solutions:

1. Verify server shows "✓ Connected" in claude mcp list
2. Restart Claude Code completely (not just terminal)
3. Check ~/.claude.json contains GitHub server config with headers
4. Verify token has correct GitHub API permissions

"No such tool available" Error

Solutions:

1. Run pre-flight check (Step 1)
2. Verify MCP server is configured: claude mcp list
3. Check token validity: op read op://... and test with GitHub API
4. Restart Claude Code after configuration

Plain Text Token Warning

Warning: Using plain text token from .env file

Risk: Token stored in plain text, visible to anyone with file access

Solution:

Convert to 1Password reference:

1. Store token in 1Password

2. Update .env:

   bash
   1GITHUB_TOKEN=op://Private/GitHub.com/GITHUB_TOKEN

3. Run configure script again

Security Best Practices

1. NEVER commit .env file - Add to .gitignore
2. NEVER commit .claude/mcp.json - Already gitignored, contains tokens
3. Use 1Password references - Never plain text tokens
4. Use local config for org-specific tokens - Prevents cross-org token leakage
5. Rotate tokens regularly - Use --reauth after rotation
6. Limit token scopes - Grant only necessary permissions
7. Audit token usage - Review GitHub token activity logs
8. Add allow patterns - Use --allow-patterns to avoid accidental permission grants

Configuration Details

MCP Server Configuration

The script configures GitHub MCP as a remote HTTP server with bearer token authentication:

Global configuration (~/.claude.json):

json
1{
2  "mcpServers": {
3    "github": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp/",
6      "headers": {
7        "Authorization": "Bearer ghp_xxxxxxxxxxxx"
8      }
9    }
10  }
11}

Local configuration (.claude/mcp.json):

json
1{
2  "mcpServers": {
3    "github": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp/",
6      "headers": {
7        "Authorization": "Bearer ghp_organization_token"
8      }
9    }
10  }
11}

Server Details:

• Type: Remote HTTP MCP server
• Host: GitHub-managed (official)
• Authentication: Bearer token in Authorization header
• Endpoint: https://api.githubcopilot.com/mcp/
• Token Source: 1Password CLI (op read)

Allow Patterns Configuration

The --allow-patterns flag adds GitHub MCP tools to ~/.claude/settings.json:

json
1{
2  "allowedTools": ["mcp__github__*"]
3}

Benefits:

• No permission prompts for GitHub MCP tools
• Faster workflow when using MCP tools frequently
• Consistent experience across sessions

Related Skills

• atlassian-mcp - Atlassian/Jira MCP integration (OAuth-based)
• secureai-mcp - SecureAI task management and security controls

References

• GitHub MCP Server Repository
• 1Password CLI Documentation
• Model Context Protocol Specification