GitHub MCP Server
๐ View on MCP Market ๐ View on MCP Registry
A Model Context Protocol (MCP) server that provides 29 Git operations + 11 workflow combinations for AI assistants and developers. This server exposes comprehensive Git repository management through a standardized interface, enabling AI models and developers to safely manage complex version control workflows.
๐ฏ About
GitHub MCP Server bridges AI assistants with Git repositories and provides powerful developer productivity tools. It provides:
- Safe Git operations through a standardized MCP interface (29 operations)
- Complete version control capabilities including advanced operations (tag, merge, rebase, cherry-pick, blame, bisect)
- 31 workflow combinations for enhanced developer productivity
- Advanced developer tools (backup, cleanup, workflow automation)
- Error handling and validation to prevent common Git mistakes
- Direct integration with VS Code and AI assistants like GitHub Copilot
- CLI wrapper for terminal access and automation
๐ Features Overview
This server provides comprehensive Git repository management through two main categories:
๐ Basic Git Operations (17 operations)
Essential daily Git commands organized in bin/basic/ - see Basic Operations Guide for detailed documentation.
- File Management: Add, remove files from staging area
- Repository Information: Status, history, differences
- Commit Operations: Create commits, push, pull
- Branch Management: Create, switch branches
- Remote Management: Add, remove, configure remotes
- Stash Operations: Temporarily save changes
- Reset Operations: Repository state management
๐ Advanced Git Operations (12 operations)
Sophisticated workflows and automation in bin/advanced/ - see Advanced Workflows Guide for comprehensive documentation.
- Workflow Combinations: Complete flows (addโcommitโpush), quick commits, sync operations
- Development Tools: Smart development workflows, backup systems
- Advanced Git Features: Tags, merging, rebasing, cherry-picking, blame, bisect
- Maintenance & Safety: Repository cleanup, optimization, backup management
- Professional Workflows: Release management, hotfix procedures, team collaboration
๐ ๏ธ Installation
๐ Quick Start with npx (Recommended)
The fastest way to use GitHub MCP Server is with npx - no installation required!
# Basic Git operations
npx github-mcp-server gstatus
npx github-mcp-server gadd
npx github-mcp-server gcommit "your commit message"
npx github-mcp-server gpush
# Advanced workflows
npx github-mcp-server gflow "implement new feature"
npx github-mcp-server gsync
npx github-mcp-server gbackup
# Or use the short alias
npx gms gstatus
npx gms gflow "quick fix"
๐ฆ Global Installation
For frequent use, install globally:
# Using npm
npm install -g github-mcp-server
# Using pnpm (recommended)
pnpm add -g github-mcp-server
# Then use directly
gstatus
gflow "your message"
gsync
๐ง Local Development Installation
See markdown/INSTALLATION.md for detailed installation guide for Windows, macOS, WSL, and all platforms.
๐ค MCP Server Integration (Cursor, Claude, etc.)
๐ฏ Cursor IDE์์ MCP ์๋ฒ ์ฌ์ฉํ๊ธฐ
Cursor์์ GitHub MCP Server๋ฅผ ์ฌ์ฉํ๋ ค๋ฉด ๋ค์ ์ค์ ์ ์ถ๊ฐํ์ธ์:
File: ~/.cursor/mcp_config.json
๐ GitHub ํ ํฐ ์ค์ (๊ถ์ฅ)
GitHub ํ ํฐ์ ์ค์ ํ๋ฉด ์ธ์ฆ ์ค๋ฅ ์์ด Git ์์ ์ ์ํํ ์ ์์ต๋๋ค:
-
GitHub Personal Access Token ์์ฑ:
- GitHub.com โ Settings โ Developer settings โ Personal access tokens โ Tokens (classic)
- "Generate new token" โ "Generate new token (classic)"
- ๊ถํ ์ค์ :
repo,workflow,write:packages๋ฑ ํ์ํ ๊ถํ ์ ํ - ํ ํฐ ์์ฑ ํ ์์ ํ ๊ณณ์ ์ ์ฅ
-
ํ๊ฒฝ๋ณ์ ์ค์ :
GITHUB_TOKEN: GitHub Personal Access TokenGITHUB_USERNAME: GitHub ์ฌ์ฉ์๋ช (์ ํ์ฌํญ, ๊ธฐ๋ณธ๊ฐ: 'git')
{
"mcpServers": {
"github-mcp-server": {
"command": "npx",
"args": ["github-mcp-server-mcp"],
"env": {
"GITHUB_TOKEN": "your_github_personal_access_token",
"GITHUB_USERNAME": "your_github_username"
},
"capabilities": ["tools", "resources", "prompts"]
}
}
}
๐ง ๋ค๋ฅธ MCP ํด๋ผ์ด์ธํธ ์ค์
Claude Desktop
File: ~/.config/claude/claude_desktop_config.json
{
"mcpServers": {
"github-mcp-server": {
"command": "npx",
"args": ["github-mcp-server", "mcp"],
"env": {}
}
}
}
Continue (VS Code Extension)
File: ~/.continue/config.json
{
"models": [
{
"title": "GitHub MCP Assistant",
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
"contextLength": 200000,
"mcpServers": [
{
"name": "github-mcp-server",
"command": "npx",
"args": ["github-mcp-server", "mcp"],
"env": {}
}
]
}
]
}
๐ MCP ์๋ฒ ์ง์ ์คํ
npm ํจํค์ง๋ก ์ค์น๋ MCP ์๋ฒ๋ฅผ ์ง์ ์คํํ ์๋ ์์ต๋๋ค:
# ๊ธ๋ก๋ฒ ์ค์น ํ
npm install -g github-mcp-server
github-mcp-server mcp
# ๋๋ npx๋ก ์ง์ ์คํ
npx github-mcp-server mcp
๐ ์ฌ์ฉ ๊ฐ๋ฅํ MCP ๋๊ตฌ๋ค
MCP ์๋ฒ๋ฅผ ํตํด ์ฌ์ฉํ ์ ์๋ 29๊ฐ Git ์์ :
- ๊ธฐ๋ณธ ์์ : git-status, git-add, git-commit, git-push, git-pull
- ๋ธ๋์น ๊ด๋ฆฌ: git-branch, git-checkout, git-merge, git-rebase
- ๊ณ ๊ธ ์์ : git-tag, git-cherry-pick, git-blame, git-bisect
- ์ํฌํ๋ก์ฐ: git-flow, git-sync, git-backup, git-clean
**์์ธํ ์ค์ ์ markdown/MCP_UNIVERSAL_CONFIG.md**๋ฅผ ์ฐธ์กฐํ์ธ์.
๐ Quick Usage Guide
๐ Basic Git Operations
# Check repository status
npx github-mcp-server gstatus
# Add all files and commit
npx github-mcp-server gadd
npx github-mcp-server gcommit "your commit message"
# Push to remote
npx github-mcp-server gpush
# Pull from remote
npx github-mcp-server gpull
# Branch operations
npx github-mcp-server gbranch feature-auth
npx github-mcp-server gcheckout feature-auth
# View history and differences
npx github-mcp-server glog 5
npx github-mcp-server gdiff main
๐ Advanced Workflows
# Complete workflow (add โ commit โ push)
npx github-mcp-server gflow "implement new feature"
# Quick commit without push
npx github-mcp-server gquick "fix typo"
# Sync with remote (pull โ push)
npx github-mcp-server gsync
# Development session management
npx github-mcp-server gdev feature-auth
# Backup and safety
npx github-mcp-server gbackup --emergency
# Repository cleanup
npx github-mcp-server gclean --optimize
๐ง Specialized Git Operations
# Tag management
npx github-mcp-server gtag create v1.0.0 "Release version"
# Merge operations
npx github-mcp-server gmerge feature-branch
# Rebase operations
npx github-mcp-server grebase main
# Cherry-pick specific commit
npx github-mcp-server gcherry abc1234
# Line-by-line authorship
npx github-mcp-server gblame src/app.js
๐ Help and Discovery
# List all available operations
npx github-mcp-server list
# Get help for specific operation
npx github-mcp-server help
# Show basic operations
npx github-mcp-server glist basic
# Show advanced workflows
npx github-mcp-server glist advanced
๐๏ธ Project Structure & Architecture
GitHub MCP Server is organized for clarity and progressive learning:
github-mcp-server/
โโโ src/
โ โโโ index.ts # MCP server (29 tool registrations, schema definitions)
โ โโโ github.ts # Git operations engine (all 29 implementations)
โโโ bin/
โ โโโ basic/ # ๐ 17 Essential Git Operations
โ โ โโโ README.md # Comprehensive basic operations guide
โ โ โโโ gadd.js # Add files (git add)
โ โ โโโ gcommit.js # Create commits (git commit)
โ โ โโโ gpush.js # Push changes (git push)
โ โ โโโ gpull.js # Pull changes (git pull)
โ โ โโโ gstatus.js # Repository status (git status)
โ โ โโโ gbranch.js # Branch management (git branch)
โ โ โโโ gcheckout.js # Branch switching (git checkout)
โ โ โโโ glog.js # Commit history (git log)
โ โ โโโ gdiff.js # Show differences (git diff)
โ โ โโโ gstash.js # Stash operations (git stash)
โ โ โโโ gpop.js # Apply stash (git stash pop)
โ โ โโโ greset.js # Reset operations (git reset)
โ โ โโโ gclone.js # Clone repositories (git clone)
โ โ โโโ gremote.js # Remote management (git remote)
โ โ โโโ ginit.js # Initialize repository (git init)
โ โโโ advanced/ # ๐ 13 Advanced Workflows & Automation
โ โโโ README.md # Comprehensive advanced workflows guide
โ โโโ gflow.js # Complete workflow (addโcommitโpush)
โ โโโ gquick.js # Quick commit workflow
โ โโโ gsync.js # Sync workflow (pullโpush)
โ โโโ gdev.js # Development session management
โ โโโ gworkflow.js # Professional workflow combinations
โ โโโ gfix.js # Smart fix and patch workflows
โ โโโ gfresh.js # Fresh start workflows
โ โโโ gbackup.js # Backup and safety operations
โ โโโ gclean.js # Repository cleanup and optimization
โ โโโ gsave.js # Save and preserve workflows
โ โโโ glist.js # Tool discovery and help system
โ โโโ grelease.js # Release management workflows
โ โโโ common.js # Shared utilities and helpers
โโโ markdown/
โ โโโ INSTALLATION.md # Detailed installation guide
โ โโโ DEPLOY.md # Production deployment guide
โ โโโ DOCKER.md # Docker setup and deployment guide
โ โโโ QUICK_REFERENCES.md # Copy-paste command reference
โโโ mcp-cli.js # Enhanced CLI wrapper (organized by structure)
โโโ package.json # Project configuration & npm scripts
โโโ tsconfig.json # TypeScript configuration
โโโ README.md # This comprehensive guide
๐ Documentation Structure
- bin/basic/README.md - Complete guide to 17 essential Git operations
- bin/advanced/README.md - Comprehensive advanced workflows documentation
- markdown/INSTALLATION.md - Step-by-step installation for all platforms
- markdown/MCP_UNIVERSAL_CONFIG.md - Universal MCP configuration for all LLM clients
- markdown/QUICK_REFERENCES.md - Copy-paste commands for quick reference
- markdown/DOCKER.md - Docker setup, deployment, and containerization
- markdown/DEPLOY.md - Production deployment and hosting strategies
๐ง Technical Architecture
๐ก MCP Server Core (src/index.ts)
- 29 Tool Registrations with complete JSON schemas
- Enhanced Metadata with operation tracking and performance monitoring
- Input Validation using Zod schemas for type safety
- Error Handling Pipeline with timeout protection and meaningful messages
- Cross-platform Compatibility with environment normalization
โ๏ธ Git Operations Engine (src/github.ts)
- Comprehensive Implementation of all 29 Git operations
- Security Features - Command injection prevention and input sanitization
- Enhanced Error Handling with context-aware messaging for common scenarios
- Performance Monitoring - Operation duration tracking and logging
- Safety Checks - Repository validation and file existence verification
๐ฅ๏ธ Enhanced CLI System
- Smart Organization - Tools categorized by basic vs advanced operations
- Directory-Aware Help - References to specific README files for detailed guidance
- Progressive Learning - Clear path from basic to advanced operations
- Tool Discovery - Enhanced
glistcommand with category filtering
๐ก๏ธ Error Handling & Safety
- ๐ Repository Validation: Ensures directory is a valid Git repository
- ๐ File Existence Checks: Validates files exist before Git operations
- โฑ๏ธ Timeout Protection: 30-second timeout for operations
- ๐ซ Input Sanitization: Prevents command injection
- ๐ Detailed Error Messages: Clear, actionable error descriptions
License
ISC License
Author
Created for use with AI assistants that support the Model Context Protocol.