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

Tool	Description	Operations	Safety Features
`git-workflow`	Core Git operations	init, status, commit, sync, backup, create, list, get, update, delete, fork, search	Repository deletion warnings
`git-files`	Read-only file operations	read, list, search, backup	File modification blocked
`git-branches`	Branch management	create, list, get, delete, merge, compare	Branch deletion warnings
`git-issues`	Issue management	create, list, get, update, close, comment, search	-
`git-pulls`	Pull request management	create, list, get, update, merge, close, review, search	-
`git-tags`	Tag management	create, list, get, delete, search	-
`git-release`	Release management	create, list, get, update, delete, publish, download	-
`git-remote`	Remote repository management	add, remove, rename, show, set-url, prune	-
`git-reset`	⚠️ Repository reset	soft, mixed, hard, reset-to-commit, reset-branch	Hard reset warnings
`git-stash`	Stash management	stash, pop, apply, list, show, drop, clear	-
`git-config`	Git configuration	get, set, unset, list, edit, show	-
`git-monitor`	Repository monitoring	status, changes, health	-
`git-backup`	Repository backup	create, restore, list, verify	-
`git-archive`	Repository archiving	create, extract, list, verify	-
`git-sync`	Repository synchronization	sync, status	-
`git-packages`	Package management	list, get, create, update, delete, publish, download	-
`git-analytics`	Repository analytics	stats, insights, reports	-

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

Code	Description	Solution
`VALIDATION_ERROR`	Parameter validation failed	Check required parameters and format
`NOT_A_GIT_REPOSITORY`	Directory is not a Git repository	Use `git init` first
`NOTHING_TO_COMMIT`	No changes to commit	Make changes first
`MERGE_CONFLICT`	Merge conflicts detected	Resolve conflicts before proceeding
`PERMISSION_DENIED`	Permission denied	Check credentials and access rights
`PROVIDER_NOT_CONFIGURED`	Provider not configured	Set up GitHub or Gitea credentials
`NETWORK_ERROR`	Network connectivity issue	Check internet connection
`OPERATION_RESTRICTED`	File modification blocked	Use read-only operations only
`SAFETY_WARNING`	Destructive operation detected	Review warning and confirm if needed

Git-Specific Error Codes

Code	Description	Solution
`BRANCH_EXISTS`	Branch already exists	Use different name or delete existing
`BRANCH_NOT_FOUND`	Branch not found	Check branch name and remote config
`DIRTY_WORKING_TREE`	Uncommitted changes	Commit or stash changes first
`DETACHED_HEAD`	Repository in detached HEAD state	Create branch or checkout existing
`REF_LOCK_ERROR`	Cannot lock Git reference	Wait for other operations to complete

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

Generate GitHub Token:
- Go to GitHub Settings → Developer settings → Personal access tokens
- Create token with repo scope
- Copy token to GITHUB_TOKEN environment variable
Generate Gitea Token:
- Go to your Gitea instance → Settings → Applications
- Generate new token with appropriate permissions
- Copy token to GITEA_TOKEN environment variable
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

Check error messages - They include specific suggestions
Review safety warnings - They explain risks and alternatives
Validate credentials - Server validates on startup
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
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

Deploy Server

A

security – no known vulnerabilities

-

license - not tested

A

quality - confirmed to work

How are these scores calculated?