# Github MCP Server πŸ”— **[View on MCP Market](https://mcpmarket.com/server/github-git-assistant)**
πŸ”— **[View on MCP Registry](https://mcp.so/server/github-mcp-server/Sharique%20Chaudhary)**
πŸ“¦ **[Available on npm](https://www.npmjs.com/package/@0xshariq/github-mcp-server)**
[![Listed on Spark](https://spark.entire.vc/badges/listed.svg)](https://spark.entire.vc/assets/vb-github?utm_source=github&utm_medium=readme) [![Install via Spark](https://spark.entire.vc/badges/vb-github/install.svg)](https://spark.entire.vc/assets/vb-github?utm_source=github&utm_medium=readme) 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. ## πŸš€ Quick Installation ### Option 1: .vscode/mcp.json (Recommended) ```bash { "mcpServers": { "github-mcp-server": { "command": "npx", "args": ["-y", "@0xshariq/github-mcp-server@latest"] } } } ``` ### Option 2: For CLI ```bash pnpm i -g @0xshariq/github-mcp-server@latest # Test Commands After Installation gstatus gadd glog 10 gpush ``` ### Option 3: Symbolic Links (Alternative - No Package Manager) ```bash # Clone and setup git clone https://github.com/0xshariq/github-mcp-server.git cd github-mcp-server npm install && npm run build # Create symbolic links (cross-platform) ./setup-symbolic.sh --user # User installation # OR sudo ./setup-symbolic.sh # System-wide (Linux/macOS) # Test the installation gstatus glist ``` > **πŸ› οΈ Having Issues?** If commands aren't working after installation, see our **[Complete Troubleshooting Guide](markdown/TROUBLESHOOTING.md)** for solutions to all common problems including "command not found" errors, path conflicts, PNPM issues, and the symbolic links alternative. ## 🎯 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/`](bin/basic/) - see **[Basic Operations Guide](bin/basic/README.md)** 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/`](bin/advanced/) - see **[Advanced Workflows Guide](bin/advanced/README.md)** 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 **See [markdown/INSTALLATION.md](markdown/INSTALLATION.md)** for detailed installation guide for Windows, macOS, WSL, and all platforms. ## πŸ—οΈ 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](bin/basic/README.md)** - Complete guide to 17 essential Git operations - **[bin/advanced/README.md](bin/advanced/README.md)** - Comprehensive advanced workflows documentation - **[markdown/INSTALLATION.md](markdown/INSTALLATION.md)** - Step-by-step installation for all platforms - **[markdown/TROUBLESHOOTING.md](markdown/TROUBLESHOOTING.md)** - πŸ› οΈ **Complete troubleshooting guide** - Solutions to all common issues - **[markdown/MCP_UNIVERSAL_CONFIG.md](markdown/MCP_UNIVERSAL_CONFIG.md)** - Universal MCP configuration for all LLM clients - **[markdown/QUICK_REFERENCES.md](markdown/QUICK_REFERENCES.md)** - Copy-paste commands for quick reference - **[markdown/DOCKER.md](markdown/DOCKER.md)** - Docker setup, deployment, and containerization - **[markdown/DEPLOY.md](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 `glist` command 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 ## πŸ› οΈ Troubleshooting Having issues with installation or commands not working? We've got you covered! Our comprehensive troubleshooting guide covers solutions to all common problems: ### 🚨 Most Common Issues & Quick Fixes | Problem | Quick Solution | | ------------------------------------------ | -------------------------------------------- | | πŸ’₯ `command not found` errors | `unset command_not_found_handle` | | πŸ“ Path conflicts with PNPM | Remove `/5/` from global directory | | πŸ”— Commands show help instead of executing | Update wrapper scripts to pass command names | | 🚫 Permission denied | `chmod +x ~/.local/share/pnpm/g*` | **πŸ‘‰ For detailed solutions, step-by-step fixes, and diagnostic tools, see our [Complete Troubleshooting Guide](markdown/TROUBLESHOOTING.md)** ### πŸ†˜ Quick Diagnostic ```bash # Test if commands are working gstatus # Should show repository status env gstatus # Alternative if above fails which gstatus # Should show path to command # If still having issues, see TROUBLESHOOTING.md for complete solutions ``` ## License ISC License ## Author Created for use with AI assistants that support the Model Context Protocol.