GitHub MCP server

GitHub MCP Server

The most comprehensive GitHub MCP server - Full GitHub workflow automation with Actions monitoring, advanced PR management, intelligent code search, and complete file management. Built for AI-powered development teams.

👉 New here? See the Quick Start Guide

🚀 AI-Optimized for Token Efficiency

This server is designed with AI agents in mind:

Response Formats

Format	Use Case	Token Savings
compact	Discovery, lists, status checks	80-97% smaller
json	Full details when needed	Full response
markdown	Human-readable display	Formatted text

Real-World Savings

Resource	Full JSON	Compact	Savings
Commit	~3,000 chars	~100 chars	97%
Issue	~2,500 chars	~150 chars	94%
Repository	~4,000 chars	~200 chars	95%
PR Overview	~20,000 chars	~1,800 chars	91% (GraphQL)

Smart Usage

// Default: Use compact for most operations
const issues = await callMCPTool("github_list_issues", {
  owner: "user", repo: "repo",
  limit: 10,
  response_format: "compact"  // 94% smaller!
});

// Use json only when you need every field
const fullIssue = await callMCPTool("github_get_issue", {
  owner: "user", repo: "repo",
  issue_number: 42,
  response_format: "json"
});

Combined with our code-first architecture (98% token reduction), you get the most efficient GitHub MCP server available.

📖 Documentation:

• Token Efficiency Guide - Detailed savings by tool (18x more efficient)
• Response Formats Reference - Complete compact field listings

✨ What's New

🚀 Latest: v2.5.6 - AI Optimization & Token Efficiency (December 18, 2025)

• 📦 Compact Format Rollout - 26 tools now support response_format: "compact" (80-97% token savings!)
• 🔧 ETag Cache Fix - Fixed critical bug where cache returned empty data on 304 responses
• 📖 AI-Agnostic Guide - CLAUDE.md renamed to MCP_GUIDE.md with instructions for Claude, Cursor, Windsurf, Copilot, Cline
• 🔒 Security Tool Docs - Added permission requirements for Dependabot, Code Scanning, Secret Scanning tools
• 📊 GraphQL Optimization - PR overview via GraphQL is 91% smaller than REST equivalent
• ✅ 320 tests passing - Full CI validation

v2.5.5 - MCP Registry Ready (December 17, 2025)

• 🔄 Removed admin-only tools (delete_repository, transfer_repository)
• ➕ Added delete tools (delete_release, delete_gist)
• 🔧 Fixed return data for create_branch, create_file, create_pull_request
• ✅ Test coverage expanded to 320 tests

Previous: v2.5.1 - Architecture Refactor & Performance (December 9, 2025)

• 🏗️ Modular Architecture - github_mcp.py split into modular package structure
• ⚡ Connection Pooling - 97% latency reduction (4000ms → 108ms for subsequent calls)
• 🔧 Dict→Model Conversion - callMCPTool now works seamlessly with plain JavaScript objects
• 📝 Multiline Code Support - Fixed truncation issues, full JSON protocol support
• ✅ Live Integration Tests - 15/15 passing, 320 total tests
• 📦 21 Tool Modules - Clean organization: tools/, models/, utils/, auth/

Previous: v2.5.0 - Phase 2 Full Send (December 4, 2025)

MAJOR RELEASE: 47 new tools added (62 → 109 total tools)! Comprehensive GitHub API coverage.

New in v2.5.0:

• 🚀 GitHub Actions Expansion (12 tools) - Complete workflow management: get/trigger workflows, manage runs/jobs, artifacts
• 🔒 Security Suite (13 tools) - Dependabot, Code Scanning, Secret Scanning, Security Advisories
• 📋 Projects (9 tools) - Classic project boards: list/create/update projects, manage columns
• 💬 Discussions (7 tools) - Community discussions: list/get discussions, categories, comments, create/update discussions, add comments (GraphQL)
• 🔔 Notifications (6 tools) - User notifications: list/manage threads, subscriptions
• 👥 Collaborators & Teams (3 tools) - Repository access management

Previous: v2.4.0 - Phase 1 Tool Expansion (December 4, 2025)

15 new tools added (48 → 62 total tools)!

New in v2.4.0:

• 🎯 Issue Comments - github_add_issue_comment for commenting on issues
• 📝 Gists - Full CRUD operations: github_list_gists, github_get_gist, github_create_gist, github_update_gist
• 🏷️ Labels - Complete label management: github_list_labels, github_create_label, github_delete_label
• ⭐ Stargazers - Star/unstar repositories: github_list_stargazers, github_star_repository, github_unstar_repository
• 👤 User Context - Enhanced user operations: github_get_authenticated_user, github_list_user_repos, github_list_org_repos, github_search_users
• ✅ Restored - github_get_user_info back in TypeScript definitions

Previous: v2.3.1 - Code-First Mode Enforced by Default (January 26, 2025)

• 🎯 Default Enforcement - Code-first mode now defaults to true (was false)
• 🚀 Zero Configuration - New users get 98% token reduction automatically
• ✅ Documentation Alignment - Code now matches documentation claims
• 🔧 Architectural Integrity - True reference implementation of code-first MCP

Previous: v2.3.0 - Architecture Formalization (January 26, 2025)

Single-Tool Architecture Formalized: The intended design from day one - one tool, 98% token reduction!

New in v2.3.0:

• 🎯 Architecture Clarification - Single-tool design formalized (always the intended architecture)
• 🛠️ CLI Utilities - Development diagnostics moved to CLI (github-mcp-cli)
• 📊 Testing Excellence - 320 tests, 63% coverage (up from 181 tests, 55%)
• ✅ 33 New Tests - Comprehensive coverage of auth, utilities, and tool operations
• 📝 Documentation Updates - Clear architecture documentation and CLI usage

---

v2.2.0 - Enterprise Ready (November 20, 2025)

GitHub App Authentication: 3x rate limits (15,000 vs 5,000 requests/hour) with fine-grained permissions!

New in v2.2.0:

• 🔐 GitHub App Authentication - Enterprise-grade auth with installation-based access
• ⚡ 3x Rate Limits - 15,000 requests/hour vs 5,000 with PAT
• 🔄 Dual Authentication - Automatic App → PAT fallback
• 🐛 19 Auth Fixes - Consistent authentication across all tools
• ✅ 100% Backward Compatible - Existing PAT users unaffected

---

v2.1.0 - Enhanced Tool Discovery (November 19, 2025)

Zero Failed Tool Calls: Intelligent tool discovery eliminates discovery issues while maintaining 98% token efficiency!

New in v2.1.0:

🔍 Tool Discovery Functions

• listAvailableTools() - Discover all tools on-demand
• searchTools(query) - Find relevant tools by keyword
• getToolInfo(name) - Get complete schemas with examples
• Discovery in code - No extra tokens loaded into Claude's context!

Benefits:

• ✅ Zero failed tool calls from discovery issues
• ✅ Professional first-time user experience
• ✅ Maintains 98% token reduction
• ✅ Complete type information for all tools

---

🎉 v2.0.0 - Revolutionary Code-First Architecture (November 18, 2025)

The Game Changer: 98% token reduction (70,000 → 800 tokens)!

New Architecture:

• Single execute_code tool exposed to Claude
• Write TypeScript code calling 112 tools on-demand
• 95% faster initialization (45s → 2s)
• 98% cost reduction ($1.05 → $0.01 per workflow)

Total Tools: 1 tool exposed to MCP clients (execute_code) 🚀
Internal Tools: 61 GitHub tools available via execute_code
Token Efficiency: 98% reduction vs traditional MCP

---

📦 Recently Shipped

v1.5.0 (Nov 6, 2025) - Infrastructure Upgrade

• Repository-rooted operations & chunk reading
• GraphQL optimization (80% faster PR queries)

View Full Changelog

---

Workspace Configuration

The workspace tools (workspace_grep, workspace_str_replace, workspace_read_file) enable powerful local file operations on YOUR projects.

What are Workspace Tools?

These tools allow Claude to:

• 🔍 Search your codebase efficiently (workspace_grep)
• ✏️ Edit files with surgical precision (workspace_str_replace)
• 📖 Read file chunks without loading entire files (workspace_read_file)

Setting Your Workspace Root

Method 1: Claude Desktop Configuration

Edit your Claude Desktop config file (location varies by OS):

macOS:

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "MCP_WORKSPACE_ROOT": "/Users/yourname/projects/my-app"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "github-mcp": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "MCP_WORKSPACE_ROOT": "C:\\Users\\yourname\\projects\\my-app"
      }
    }
  }
}

Linux:

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "MCP_WORKSPACE_ROOT": "/home/yourname/projects/my-app"
      }
    }
  }
}

Method 2: Environment Variable

macOS/Linux:

export MCP_WORKSPACE_ROOT="/path/to/your/project"
python3 -m github_mcp

Windows (Command Prompt):

set MCP_WORKSPACE_ROOT=C:\path\to\your\project
python -m github_mcp

Windows (PowerShell):

$env:MCP_WORKSPACE_ROOT="C:\path\to\your\project"
python -m github_mcp

Method 3: Default Behavior

If MCP_WORKSPACE_ROOT is not set, tools will use your current working directory as the workspace root.

Workspace Security

• ✅ Tools can ONLY access files within the workspace root
• ✅ Path traversal attempts are blocked
• ✅ No access outside your project directory
• ✅ Safe for production use

Example Usage

# After setting MCP_WORKSPACE_ROOT="/Users/dave/my-app"

# Search for TODOs in your project
workspace_grep("TODO", file_pattern="*.py")

# Read a specific file chunk
workspace_read_file("src/main.py", start_line=1, num_lines=50)

# Make surgical edits
workspace_str_replace(
    path="config/settings.py",
    old_str="DEBUG = True",
    new_str="DEBUG = False",
    description="Disable debug mode for production"
)

Use Cases

• 🔧 Local Development: Work on files before committing
• 🔍 Code Search: Find patterns across your entire project
• ✏️ Refactoring: Make precise changes without touching GitHub
• 📊 Analysis: Read and analyze code structure

GitHub Remote Tools

For working with files directly on GitHub (no cloning required):

• github_grep - Search patterns in GitHub repository files

  • Verify code exists after pushing changes
  • Search across branches or specific commits
  • Find patterns in remote repos without cloning
  • 90%+ token savings vs fetching full files

• github_read_file_chunk - Read specific line ranges from GitHub files

  • Read just the lines you need (50-500 lines)
  • Perfect for reviewing functions or sections
  • 90%+ token savings vs fetching full files

• github_str_replace - Make surgical edits to GitHub files

  • Update files directly on GitHub without cloning
  • Perfect for quick fixes, version updates, or documentation changes
  • Requires write access to repository

Complete Workflow:

1. Develop locally with workspace tools (fast, token-efficient)
2. Push changes via git
3. Verify on GitHub with github tools (confirm changes are live)
4. Make quick fixes directly on GitHub if needed

---

🏗️ Architecture: Code-First MCP

How It Works

The GitHub MCP Server uses code-first architecture - a revolutionary approach that reduces token usage by 98% while maintaining full functionality.

What You See

When you install this server in your MCP client (Cursor, Claude Desktop, etc.):

• One tool: execute_code
• Token cost: ~800 tokens
• All functionality: Access to 109 GitHub tools

What Happens Under The Hood

┌─────────────────────────────────┐
│   MCP Client                    │
│   Sees: execute_code (1 tool)   │
└────────────┬────────────────────┘
             │
             ↓ You write TypeScript code
┌─────────────────────────────────┐
│   Deno Runtime                  │
│   Executes your code securely   │
│   Access to all internal tools  │
│   via callMCPTool()             │
└─────────────────────────────────┘

Traditional MCP vs Code-First

Aspect	Traditional MCP	Code-First MCP (Us)
Tools exposed	112 tools	1 tool
Token cost	~70,000	~800
Reduction	-	98%
Functionality	Same	Same
Flexibility	Tool calls only	Code + logic + loops

Why This Matters

• Massive token savings: 98% reduction means faster responses and lower costs
• Complex workflows: Combine multiple operations in single execution
• Conditional logic: Use if/else, loops, and full programming capability
• Same functionality: All 112 tools still available (111 internal + execute_code wrapper)

This architecture validates Anthropic's research predictions about code-first MCP.

🔍 Tool Discovery

The GitHub MCP Server includes powerful tool discovery functions to help you find and understand tools quickly.

searchTools(keyword)

Search for tools by keyword. Searches tool names, descriptions, categories, and parameters with relevance scoring.

Example:

// Find all issue-related tools
const issueTools = searchTools("issue");
// Returns: Array of tools sorted by relevance

issueTools.forEach(tool => {
  console.log(`${tool.name} (relevance: ${tool.relevance})`);
  console.log(`  Category: ${tool.category}`);
  console.log(`  Matched in: ${tool.matchedIn.join(", ")}`);
});

// Output:
// github_create_issue (relevance: 15)
//   Category: Issues
//   Matched in: name, description

Returns:

Array<{
  name: string;           // Tool name
  category: string;       // Category (e.g., "Issues")
  description: string;    // Tool description
  relevance: number;      // Relevance score (higher = better match)
  matchedIn: string[];    // Where matches were found
  tool: object;          // Full tool object
}>

Relevance Scoring:

• Tool name match: +10 points
• Description match: +5 points
• Category match: +3 points
• Parameter name match: +2 points
• Parameter description match: +1 point

getToolInfo(toolName)

Get complete details about a specific tool including parameters, usage, and metadata.

Example:

// Get detailed info about a tool
const info = getToolInfo("github_create_issue");

console.log(`Name: ${info.name}`);
console.log(`Category: ${info.category}`);
console.log(`Description: ${info.description}`);
console.log(`Usage: ${info.usage}`);

// See metadata
console.log(`Total tools: ${info.metadata.totalTools}`);
console.log(`Tools in category: ${info.metadata.categoryTools}`);

// Check parameters
Object.entries(info.parameters).forEach(([name, param]) => {
  console.log(`${name}: ${param.type} ${param.required ? '(required)' : '(optional)'}`);
  console.log(`  ${param.description}`);
});

Returns:

{
  name: string;              // Tool name
  category: string;          // Category
  description: string;       // Description
  parameters: object;        // Parameter definitions
  returns: string;           // Return value description
  example: string;           // Code example
  usage: string;            // Usage syntax
  metadata: {
    totalTools: number;      // Total available tools
    categoryTools: number;   // Tools in same category
    relatedCategory: string; // Category name
  }
}

Error Handling:

const info = getToolInfo("nonexistent_tool");
// Returns: { error: "Tool not found", suggestion: "Use searchTools()...", availableTools: 42 }

Workflow Example: Discover → Learn → Use

// 1. Discover tools
const prTools = searchTools("pull request");
console.log(`Found ${prTools.length} PR-related tools`);

// 2. Learn about the best match
const bestMatch = prTools[0];
const info = getToolInfo(bestMatch.name);
console.log(`Using: ${info.name}`);
console.log(`Required params: ${Object.keys(info.parameters).filter(k => info.parameters[k].required).join(", ")}`);

// 3. Use the tool
const result = await callMCPTool(info.name, {
  owner: "facebook",
  repo: "react",
  state: "open"
});

Available Discovery Functions

Function	Purpose	Returns
listAvailableTools()	Get all tools organized by category	Full tool catalog
searchTools(keyword)	Find tools by keyword	Relevance-sorted matches
getToolInfo(toolName)	Get complete tool details	Full tool information
callMCPTool(name, params)	Execute a tool	Tool result

This discovery happens inside your TypeScript code - no extra tools loaded into Claude's context!

Development Utilities (CLI)

For server diagnostics and development, we provide CLI commands (these are NOT MCP tools):

# Check server health
github-mcp-cli health

# Clear GitHub App token cache  
github-mcp-cli clear-cache

# Verify Deno runtime installation
github-mcp-cli check-deno

Note: These CLI utilities are for development and debugging only. They are not exposed to MCP clients and were created for testing the server itself during development.

Simple Setup

macOS/Linux:

{
  "mcpServers": {
    "github": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Note: Code-first mode is enforced by the architecture. No additional configuration is needed. You get 98% token savings automatically.

That's it! You get 98% token savings by default. 🚀

Learn More

• 📖 Code Execution Guide - Complete documentation
• 💡 Examples - Real-world usage examples
• 🚀 Quick Start - 5-minute setup

---

🙏 Built on Anthropic's Research

This server implements the code-first MCP pattern described in Anthropic's research:

📄 Blog: "Code execution with MCP"
👥 Authors: Adam Jones & Conor Kelly

Their prediction: 98.7% token reduction (150,000 → 2,000 tokens)
Our validation: 98% token reduction (70,000 → 800 tokens)

Thank you to the Anthropic team for pioneering this approach! 🎉

Learn more about our implementation →

Requirements

• Deno runtime installed
• GitHub authentication (Personal Access Token or GitHub App)

---

⚙️ Configuration & Authentication

Dual Authentication Strategy (Recommended)

For maximum functionality and rate limits, you can configure both authentication methods, but most users only need a PAT to start:

{
  "mcpServers": {
    "github-mcp": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        // === Personal Access Token (Simple default - REQUIRED for releases) ===
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here",
        
        // === Optional: GitHub App Authentication (Advanced) ===
        "GITHUB_APP_ID": "123456",
        "GITHUB_APP_INSTALLATION_ID": "12345678",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/path/to/private-key.pem",
        
        // === Optional: Workspace for local file operations ===
        "MCP_WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}

Why Both Authentication Methods?

🏆 GitHub App Authentication (Advanced)

• Rate Limit: 15,000 requests/hour (3x better than PAT)
• Best For: Most operations, team collaboration, production use
• Covers: Repository management, issues, PRs, files, search, workflows

Setup GitHub App:

1. Go to GitHub Settings → Developer settings → GitHub Apps → New GitHub App
2. Set permissions: Contents (read/write), Issues (read/write), Pull requests (read/write), Metadata (read)
3. Install the app on your account/organization
4. Generate and download private key
5. Note your App ID and Installation ID

🔑 Personal Access Token (Required Fallback)

• Rate Limit: 5,000 requests/hour
• Required For: Release operations (GitHub App limitation)
• Also Covers: All operations if GitHub App unavailable

Why PAT is Required:

GitHub Apps have a permission limitation - they cannot create/manage releases that involve tagging commits (the "releases" permission scope is not available for GitHub Apps). The following operations require PAT fallback:

• ✅ github_create_release - Creating releases with tags
• ✅ github_update_release - Updating release information
• ✅ Any operation involving non-HEAD commit tagging

The server automatically falls back to PAT for these operations even if GitHub App is configured.

Create PAT:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token with scopes: repo, workflow
3. Copy the token (you won't see it again!)

Authentication Behavior

Operation Requested
    ↓
Try GitHub App (if configured)
    ↓
├─ Success → Use App (15k rate limit) ✅
└─ Fails or requires releases permission
       ↓
   Fall back to PAT (if configured)
       ↓
   ├─ Success → Use PAT (5k rate limit) ✅
   └─ Fails → Return auth error ❌

Quick Start Configuration

Most users just need a Personal Access Token:

1. Create a GitHub PAT:

• Go to https://github.com/settings/tokens
• Click "Generate new token (classic)"
• Select scopes: repo, workflow, read:org
• Copy the token

2. Configure your MCP client:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Or using system environment variables:

Set GITHUB_TOKEN in your shell profile or system environment settings.

That's it! You're ready to use all 112 tools.

💡 Need higher rate limits? Power users can create their own GitHub App for 15,000 requests/hour instead of 5,000.

Platform-Specific Examples

macOS

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_APP_ID": "123456",
        "GITHUB_APP_INSTALLATION_ID": "12345678",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/Users/yourname/.github/private-key.pem",
        "GITHUB_TOKEN": "ghp_your_token",
        "MCP_WORKSPACE_ROOT": "/Users/yourname/projects/my-app"
      }
    }
  }
}