Andre-Buzeli/git-mcp

GIT MCP Server

Professional MCP (Model Context Protocol) server for Git operations with multi-provider support, enhanced security, and comprehensive safety features.

Features

• 🚀 17 Specialized Git Tools - Complete Git workflow coverage with safety warnings
• 🔄 Multi-Provider Support - GitHub and Gitea simultaneously with credential validation
• 🔒 Security-First Design - Read-only file operations, no content modification via API
• 🚨 Safety Warnings - Comprehensive warnings for destructive operations
• 🛡️ Enhanced Error Handling - Detailed diagnostics with actionable solutions
• 📋 Comprehensive Validation - Pre-execution validation with helpful guidance
• 🔧 IDE/Client Compatibility - Universal aliases for different MCP client expectations
• 📦 NPM Distribution - Easy installation via npx
• 🤖 AI Agent Integration - Designed for AI agent workflows with safety controls

Quick Start

Installation & Usage

# Run directly with npx (recommended)
npx @andrebuzeli/git-mcp@latest

# Or install globally
npm install -g @andrebuzeli/git-mcp
git-mcp

Configuration

Set up your provider credentials via environment variables:

GitHub Configuration

export GITHUB_TOKEN="your_github_token"
export GITHUB_USERNAME="your_username"

Gitea Configuration

export GITEA_URL="https://your-gitea-instance.com"
export GITEA_TOKEN="your_gitea_token"
export GITEA_USERNAME="your_username"

Multi-Provider Support

Configure both GitHub and Gitea to use provider="both" in tool calls.

Available Tools

Security Features

🔒 File Operations Restriction

The git-files tool is read-only only for security reasons:

✅ Allowed Operations:

• read - Read file content
• list - List directory contents
• search - Search file content
• backup - Create local backups

❌ Blocked Operations:

• create - Create new files (blocked)
• update - Modify existing files (blocked)
• delete - Delete files (blocked)

Why? File content modification should be done through your local development environment, not via remote API calls.

🚨 Safety Warnings

Destructive operations include comprehensive safety warnings:

Git Reset Warnings

{
  "tool": "git-reset",
  "params": {
    "action": "hard",
    "projectPath": "/path/to/project"
  }
}

Result: Detailed warning about data loss with alternatives:

• git reset --soft (keeps changes staged)
• git reset --mixed (keeps changes unstaged)
• git stash (saves changes temporarily)

Branch Deletion Warnings

{
  "tool": "git-branches", 
  "params": {
    "action": "delete",
    "branchName": "feature-branch"
  }
}

Result: Warning about permanent branch deletion with suggestions:

• Ensure branch is merged first
• Create backup branch before deletion
• Check for unmerged commits

🔍 Enhanced Error Handling

All tools provide detailed error messages with actionable solutions:

Example Error Response:

{
  "success": false,
  "error": {
    "code": "BRANCH_NOT_FOUND",
    "message": "Branch not found",
    "suggestions": [
      "Check if the branch name is correct",
      "Use git branch -a to see all available branches", 
      "Ensure the branch exists on the remote repository"
    ]
  }
}

Usage Examples

Local Git Operations

{
  "tool": "git-workflow",
  "params": {
    "action": "status",
    "projectPath": "/path/to/project"
  }
}

{
  "tool": "git-workflow", 
  "params": {
    "action": "commit",
    "projectPath": "/path/to/project",
    "message": "Add new feature"
  }
}

Remote Repository Operations

{
  "tool": "git-workflow",
  "params": {
    "action": "create",
    "projectPath": "/path/to/project", 
    "provider": "github",
    "name": "my-new-repo",
    "description": "My new repository",
    "private": true
  }
}

Safe File Operations (Read-Only)

{
  "tool": "git-files",
  "params": {
    "action": "read",
    "projectPath": "/path/to/project",
    "filePath": "README.md"
  }
}

Destructive Operations (With Warnings)

{
  "tool": "git-reset",
  "params": {
    "action": "hard",
    "projectPath": "/path/to/project",
    "confirmDestructive": true
  }
}

Error Codes Reference

Common Error Codes

Git-Specific Error Codes

Configuration Guide

Environment Variables

Required for GitHub:

• GITHUB_TOKEN - Personal access token with repo permissions
• GITHUB_USERNAME - Your GitHub username

Required for Gitea:

• GITEA_URL - Your Gitea instance URL (e.g., https://git.example.com)
• GITEA_TOKEN - Personal access token
• GITEA_USERNAME - Your Gitea username

Credential Validation

The server automatically validates credentials on startup:

• ✅ Valid credentials - API connectivity confirmed
• ❌ Invalid token - Authentication failed
• 🌐 Network error - Cannot reach provider API
• ⚠️ Partial failure - Some providers failed validation

Setup Instructions

1. Generate GitHub Token:

   • Go to GitHub Settings → Developer settings → Personal access tokens
   • Create token with repo scope
   • Copy token to GITHUB_TOKEN environment variable

2. Generate Gitea Token:

   • Go to your Gitea instance → Settings → Applications
   • Generate new token with appropriate permissions
   • Copy token to GITEA_TOKEN environment variable

3. Test Configuration:

   # Start the server to see validation results
   npx @andrebuzeli/git-mcp@latest
   

Troubleshooting

Common Issues

"Provider not configured" error:

• Check environment variables are set correctly
• Verify token has required permissions
• Test API connectivity manually

"Operation restricted" error:

• File modification operations are blocked for security
• Use read-only operations: read, list, search, backup
• Make file changes through your local development environment

"Safety warning" error:

• Review the detailed warning message
• Consider safer alternatives suggested
• Use confirmDestructive: true only if absolutely necessary

"Network error" errors:

• Check internet connectivity
• Verify provider URLs are correct
• Check firewall/proxy settings

Getting Help

1. Check error messages - They include specific suggestions
2. Review safety warnings - They explain risks and alternatives
3. Validate credentials - Server validates on startup
4. Use read-only operations - Safe file operations are always available

Development

Building from Source

git clone https://github.com/your-repo/git-mcp.git
cd git-mcp
npm install
npm run build

Testing

npm test

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

⚠️ Important Security Notes:

• File content modification is intentionally restricted for security
• Always review safety warnings before destructive operations
• Keep your API tokens secure and rotate them regularly
• Use confirmDestructive: true only when absolutely necessary