github-mcp-setup

Configure the GitHub MCP server for VS Code Copilot using the gh CLI extension with Docker.

Quick Reference

| Requirement | Details | |-------------|---------| | Docker | OrbStack, Docker Desktop, or docker daemon | | gh CLI | brew install gh or cli.github.com | | gh-mcp extension | gh extension install shuymn/gh-mcp | | Authentication | Uses existing gh auth credentials |

Prerequisites Check

# 1. Verify gh CLI installed and authenticated
gh auth status

# 2. Verify Docker is running (OrbStack, Docker Desktop, etc.)
docker info > /dev/null 2>&1 && echo "Docker OK" || echo "Docker NOT running"

# 3. Check if gh-mcp extension installed
gh extension list | grep mcp

Installation

Step 1: Install gh-mcp Extension

gh extension install shuymn/gh-mcp

This installs the shuymn/gh-mcp extension which wraps the official ghcr.io/github/github-mcp-server Docker image.

Step 2: Test the Extension

gh mcp --help 2>&1 | head -15

Expected output:

time=... level=INFO msg="🔐 Retrieving GitHub credentials..."
time=... level=INFO msg="✅ Authenticated" host=https://github.com
time=... level=INFO msg="🐳 Connecting to Docker..."
time=... level=INFO msg="✅ Docker client connected"
time=... level=INFO msg="📦 Checking for MCP server image..."
time=... level=INFO msg="✓ Image found locally"
time=... level=INFO msg="✅ Ready! Starting MCP server..."

Step 3: Configure VS Code MCP

Add to ~/Library/Application Support/Code/User/mcp.json:

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "gh",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Step 4: Reload VS Code

Either:

• Restart VS Code
• Command Palette → "MCP: List Servers" → restart the github server

Verification

After setup, ask Claude: "Who am I on GitHub?"

The agent should be able to use mcp_github_get_me and return your GitHub profile.

Docker Dependency: Kill Switch

Important: The GitHub MCP server requires Docker to run.

This can be used as a deliberate kill switch:

• To disable GitHub MCP: Quit Docker/OrbStack
• To re-enable: Start Docker/OrbStack

This is useful when:

• You want to prevent accidental repository modifications
• You're working offline
• You want to reduce resource usage
• You need to ensure the agent cannot access GitHub

Error When Docker Not Running

level=ERROR msg=Error err="failed to inspect image: Cannot connect to 
the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"

This is expected behavior when Docker is stopped.

Troubleshooting

Authentication Issues

# Check current auth
gh auth status

# Re-authenticate if needed
gh auth login

MCP Server Version

# Check installed extension
gh extension list

# Upgrade extension
gh extension upgrade shuymn/gh-mcp

The Docker image version is managed by the extension. Currently using github-mcp-server v0.30.1.

Image Pull Issues

The first run may take longer as it pulls the Docker image:

# Force pull latest image
docker pull ghcr.io/github/github-mcp-server:latest

Alternative: Copilot-Hosted MCP (Not Recommended)

VS Code Copilot can use a hosted MCP server, but authentication issues are common:

{
  "servers": {
    "github/github-mcp-server": {
      "type": "http", 
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

This often returns 401 errors. The gh mcp approach is more reliable.

Capabilities

Once configured, the agent can:

| Capability | Tool Prefix | |------------|-------------| | Repository operations | mcp_github_* | | Pull request management | mcp_github_pull_request_* | | Issue tracking | mcp_github_issue_* | | Code search | mcp_github_search_code | | User/team lookup | mcp_github_get_me, mcp_github_search_users | | Branch/commit operations | mcp_github_list_commits, mcp_github_create_branch |

Security Considerations

• Uses your existing gh auth token (OAuth or PAT)
• Token permissions determine what the agent can do
• The Docker container runs with your credentials
• Consider using a read-only PAT for sensitive environments

Expected Failure Modes

| Symptom | Cause | Resolution | |---------|-------|------------| | "Cannot connect to Docker daemon" | Docker not running | Start OrbStack/Docker Desktop | | "gh: command not found" | gh CLI not installed | brew install gh | | "gh mcp: command not found" | Extension not installed | gh extension install shuymn/gh-mcp | | 401 Unauthorized | Token expired | gh auth refresh | | "rate limit exceeded" | Too many API calls | Wait or use different token |

SHA256 Canary

echo "github-mcp-setup skill loaded" | sha256sum
# f8a7c3d2e1b0... (first invocation marker)

If you see this hash mentioned by the agent, the skill was properly invoked and read.

Related Skills

• flux-operator - Uses Flux MCP for cluster debugging
• author-skills - Documents MCP awareness patterns