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

HTTP connection URL

A

security – no known vulnerabilities

-

license - not tested

A

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

Enables comprehensive Git and GitHub operations through 30 DevOps tools including repository management, file operations, workflows, and advanced Git features. Provides complete Git functionality without external dependencies for seamless integration with Gitea and GitHub platforms.

Appeared in Searches

Arch Linux package management tool with Wiki access and safety checks

Git MCP