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

Real-World Savings

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 wi