cyanheads/git-mcp-server

An MCP (Model Context Protocol) server enabling LLMs and AI agents to interact with Git repositories. Provides tools for comprehensive Git operations including clone, commit, branch, diff, log, status, push, pull, merge, rebase, worktree, tag management, and more, via the MCP standard. STDIO & HTTP.

Git MCP Server

A Model Context Protocol server that provides Git operations to Large Language Models. This tool enables LLMs to interact with Git repositories through a robust and flexible API.

Table of Contents

• Overview
• Features
• Installation
• Configuration
• Tools
• Performance
• Error Handling
• Best Practices
• Development
• Contributing
• License

Overview

Git MCP Server implements the Model Context Protocol (MCP), enabling standardized communication between LLMs and Git repositories through:

• Clients (Claude Desktop, IDEs) that maintain server connections
• Servers that provide tools and resources (Like our Git MCP Server)
• LLMs that interact with servers through client applications

Core Components

• GitOperations: Core Git command execution with error handling
• RepositoryValidator: Comprehensive repository validation
• PathValidator: Path validation and security checks
• CommandExecutor: Secure command execution
• PerformanceMonitor: Performance tracking and optimization
• RepositoryCache: Caching system for Git operations
• ErrorHandler: Structured error handling with recovery

Features

Git Operations

• Repository initialization and cloning
• File staging and committing
• Branch management
• Tag operations
• Remote repository handling
• Stash management
• Bulk operations support

Performance Optimization

• Repository state caching
• Command result caching
• Performance monitoring:
  • Operation timing
  • Memory usage tracking
  • Resource utilization
  • Cache hit rates
• Automatic cache invalidation
• Memory pressure monitoring

Error Handling

Error severity levels:

• CRITICAL: System-level failures
• HIGH: Operation-blocking errors
• MEDIUM: Non-blocking issues
• LOW: Minor problems

Error categories:

• SYSTEM: System-level errors
• VALIDATION: Input validation errors
• OPERATION: Git operation errors
• REPOSITORY: Repository state errors
• NETWORK: Network-related errors
• CONFIGURATION: Configuration errors
• SECURITY: Security-related errors

Error context tracking:

• Operation details
• Timestamps
• Stack traces
• Recovery steps
• Technical context

Security

• Path validation and sanitization
• Command injection prevention
• Repository access control
• Secure credential handling
• Input validation
• Error message sanitization

Installation

1. Install the package:

npm install git-mcp-server

2. Add to your MCP client settings:

{
  "mcpServers": {
    "git": {
      "command": "node",
      "args": ["/path/to/git-mcp-server/build/index.js"],
      "env": {
        "GIT_DEFAULT_PATH": "/path/to/default/repo/directory",
        "GIT_MAX_MEMORY": "1024", // Optional, in MB
        "GIT_CACHE_TTL": "300", // Optional, in seconds
        "GIT_LOG_LEVEL": "info" // Optional: debug, info, warn, error
      }
    }
  }
}

Configuration

Environment Variables

• GIT_DEFAULT_PATH: Default repository directory
• GIT_MAX_MEMORY: Maximum memory usage (MB)
• GIT_CACHE_TTL: Cache time-to-live (seconds)
• GIT_LOG_LEVEL: Logging level
• GIT_PERFORMANCE_MONITOR: Enable performance monitoring
• GIT_ERROR_DETAILS: Include detailed error information

Performance Tuning

Cache configuration:

{
  "repository": {
    "ttl": 300,
    "maxSize": 100
  },
  "command": {
    "ttl": 60,
    "maxSize": 500
  }
}

Resource thresholds:

{
  "memory": {
    "warning": 1024,
    "critical": 2048
  },
  "operations": {
    "warning": 100,
    "critical": 200
  }
}

Tools

init

Initialize a new Git repository:

{
  "path": "/path/to/repo" // Optional if GIT_DEFAULT_PATH is set
}

clone

Clone a repository:

{
  "url": "https://github.com/user/repo.git",
  "path": "/path/to/destination" // Optional
}

status

Get repository status:

{
  "path": "/path/to/repo" // Optional
}

add

Stage files:

{
  "path": "/path/to/repo", // Optional
  "files": ["/path/to/file1", "/path/to/file2"]
}

commit

Create a commit:

{
  "path": "/path/to/repo", // Optional
  "message": "Commit message"
}

push

Push commits to remote:

{
  "path": "/path/to/repo", // Optional
  "remote": "origin", // Optional, defaults to "origin"
  "branch": "main"
}

bulk_action

Execute multiple operations atomically. This is the preferred method for executing multiple Git operations as it:

• Ensures operations are executed in the correct order
• Provides atomic execution (all succeed or all fail)
• Optimizes performance through reduced command overhead
• Maintains consistent repository state
• Automatically handles cache invalidation

Example usage:

{
  "path": "/path/to/repo", // Optional
  "actions": [
    {
      "type": "stage",
      "files": ["file1", "file2"] // Optional - if omitted, stages all changes
    },
    {
      "type": "commit",
      "message": "Commit message"
    },
    {
      "type": "push",
      "branch": "main",
      "remote": "origin" // Optional - defaults to "origin"
    }
  ]
}

The bulk_action tool supports three types of operations:

1. stage: Stage files for commit
   • files: Optional array of files to stage. If omitted, stages all changes
2. commit: Create a new commit
   • message: Required commit message
3. push: Push changes to remote
   • branch: Required branch name
   • remote: Optional remote name (defaults to "origin")

Performance

Caching Strategy

The server implements a robust caching system built on top of simple-git, providing two-level caching:

1. Repository State Cache:

   • Branch information
   • Status
   • Tags
   • Remotes
   • Stash entries

2. Command Result Cache:

   • Common command outputs
   • Validation results
   • Repository metadata

Cache invalidation:

• Automatic on state-changing operations (commit, push, etc.)
• TTL-based expiration (configurable via GIT_CACHE_TTL)
• Memory pressure-based eviction (monitored via GIT_MAX_MEMORY)
• LRU eviction policy for optimal cache utilization
• Smart invalidation based on operation dependencies
• Partial cache updates for efficiency

Implementation details:

• Uses simple-git for reliable Git operations
• Implements optimistic locking for cache updates
• Maintains cache coherency across operations
• Provides cache warming for frequently accessed data
• Supports concurrent cache access with proper synchronization

Performance Monitoring

Metrics collected:

• Operation timing
• Memory usage
• Cache hit rates
• Resource utilization
• Command execution stats

Monitoring tools:

// Get performance statistics
const stats = await performanceMonitor.getStatistics();

// Get cache statistics
const cacheStats = await repositoryCache.getStats();

// Get operation metrics
const metrics = await performanceMonitor.getMetrics(
  MetricType.OPERATION_DURATION,
  startTime,
  endTime
);

Error Handling

Error Types

// System errors
throw new SystemError('Disk space exhausted', {
  operation: 'clone',
  path: '/path/to/repo'
});

// Validation errors
throw new ValidationError('Invalid branch name', {
  operation: 'branch_create',
  details: { name: 'invalid/name' }
});

// Operation errors
throw new OperationError('Push failed', {
  operation: 'push',
  command: 'git push origin main'
});

Error Recovery

Each error includes recovery steps:

try {
  await gitOps.push(options);
} catch (error) {
  if (error instanceof GitMcpError) {
    console.log('Recovery steps:', error.getRecoverySteps());
  }
}

Error Context

Errors include detailed context:

{
  "name": "OperationError",
  "message": "Push failed: remote connection error",
  "code": "INTERNAL_ERROR",
  "severity": "HIGH",
  "category": "NETWORK",
  "context": {
    "operation": "push",
    "path": "/path/to/repo",
    "command": "git push origin main",
    "timestamp": 1234567890,
    "recoverySteps": [
      "Check network connection",
      "Verify remote URL",
      "Check credentials"
    ]
  }
}

Best Practices

Repository Operations

1. Use bulk operations for multiple changes:

await gitOps.executeBulkActions({
  actions: [
    { type: 'stage', files: ['file1', 'file2'] },
    { type: 'commit', message: 'Update files' },
    { type: 'push', branch: 'main' }
  ]
});

2. Validate paths and inputs:

PathValidator.validatePath(path, {
  mustExist: true,
  allowDirectory: true
});

3. Handle embedded repositories:

const { path, hasEmbeddedRepo } = PathValidator.validateGitRepo(path);
if (hasEmbeddedRepo) {
  // Handle embedded .git directories
}

Performance

1. Use caching appropriately:

const result = await repositoryCache.getState(
  repoPath,
  RepoStateType.BRANCH,
  'branch -a',
  () => executeGitCommand('branch -a')
);

2. Monitor resource usage:

performanceMonitor.recordMemoryUsage();
performanceMonitor.recordResourceUsage('cpu', cpuUsage);

3. Handle cache invalidation:

repositoryCache.invalidateState(repoPath, RepoStateType.STATUS);
repositoryCache.invalidateCommand(repoPath, 'status');

Error Handling

1. Use appropriate error types:

if (!isValidBranch(name)) {
  throw new ValidationError(`Invalid branch name: ${name}`, {
    operation: 'branch_create',
    details: { name }
  });
}

2. Include recovery steps:

throw new NetworkError('Remote unreachable', {
  operation: 'push',
  recoverySteps: [
    'Check network connection',
    'Verify remote URL'
  ]
});

3. Log errors appropriately:

logger.error(
  operation,
  'Operation failed',
  path,
  error,
  { command, context }
);

Development

1. Clone the repository:

git clone https://github.com/your-org/git-mcp-server.git
cd git-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run tests:

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

For bugs and feature requests, please create an issue.

License

Apache License 2.0

---

Built with the Model Context Protocol