Git MCP Server

🛠️ Tools Overview

This server provides 27 comprehensive Git operations organized into six functional categories:

Related MCP server: GitHub MCP Server

📦 Resources Overview

The server provides resources that offer contextual information about the Git environment:

🎯 Prompts Overview

The server provides structured prompt templates that guide AI agents through complex workflows:

🚀 Getting Started

Runtime Compatibility

This server works with both Bun and Node.js runtimes:

The server automatically detects the runtime and uses the appropriate process spawning method for git operations.

MCP Client Settings/Configuration

Add the following to your MCP Client configuration file (e.g., cline_mcp_settings.json). Clients have different ways to configure servers, so refer to your client's documentation for specifics.

Be sure to update environment variables as needed (especially your Git information!)

Using npx (Node.js)

Using bunx (Bun)

Streamable HTTP Configuration

✨ Server Features

This server is built on the mcp-ts-template and inherits its rich feature set:

• Declarative Tools: Define agent capabilities in single, self-contained files. The framework handles registration, validation, and execution.

• Robust Error Handling: A unified McpError system ensures consistent, structured error responses.

• Pluggable Authentication: Secure your server with zero-fuss support for none, jwt, or oauth modes.

• Abstracted Storage: Swap storage backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic.

• Full-Stack Observability: Deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.

• Dependency Injection: Built with tsyringe for a clean, decoupled, and testable architecture.

• Edge-Ready Architecture: Built on an edge-compatible framework that runs seamlessly on local machines or Cloudflare Workers. Note: Current git operations use the CLI provider which requires local git installation. Edge deployment support is planned through the isomorphic-git provider integration.

Plus, specialized features for Git integration:

• Cross-Runtime Compatibility: Works seamlessly with both Bun and Node.js runtimes. Automatically detects the runtime and uses optimal process spawning (Bun.spawn in Bun, child_process.spawn in Node.js).

• Provider-Based Architecture: Pluggable git provider system with current CLI implementation and planned isomorphic-git provider for edge deployment.

• Optimized Git Execution: Direct git CLI interaction with cross-runtime support for high-performance process management, streaming I/O, and timeout handling (current CLI provider).

• Comprehensive Coverage: 27 tools covering all essential Git operations from init to push.

• Working Directory Management: Session-specific directory context for multi-repo workflows.

• Configurable Git Identity: Override author/committer information via environment variables with automatic fallback to global git config.

• Safety Features: Explicit confirmations for destructive operations like git clean and git reset --hard.

• Commit Signing: Optional GPG/SSH signing support for all commit-creating operations (commits, merges, rebases, cherry-picks, and tags).

Development Environment Setup

Prerequisites

• Node.js v20.0.0+ (or Bun v1.2.0+ as an alternative)

• Git installed and accessible in your system PATH

Installation

1. Clone the repository:

2. Navigate into the directory:

3. Install dependencies:

⚙️ Configuration

All configuration is centralized and validated at startup in src/config/index.ts. Key environment variables in your .env file include:

▶️ Running the Server

For End Users (via Package Manager)

The easiest way to use the server is via npx (no installation required):

Configured through environment variables or your MCP client configuration. Bun users can alternatively use bunx @cyanheads/git-mcp-server@latest.

Local Development

• Build and run the production version:

  # One-time build npm run rebuild # Run the built server npm run start:http # or npm run start:stdio

• Development mode with hot reload:

  npm run dev:http # or npm run dev:stdio

• Run checks and tests:

  npm run devcheck # Lints, formats, type-checks, and more npm test # Runs the test suite

Cloudflare Workers

1. Build the Worker bundle:

2. Run locally with Wrangler:

3. Deploy to Cloudflare:

📂 Project Structure

📤 Understanding Tool Responses

This server follows MCP's dual-output architecture for all tools (MCP Tools Specification):

Response Format Options

Configure response format and verbosity via environment variables (see Configuration):

What Users See (Human-Readable)

When you invoke a tool through your MCP client, you see a formatted summary designed for human consumption. For example, git_status might show:

Markdown Format:

JSON Format (LLM-Optimized):

What the LLM Sees (Complete Structured Data)

Behind the scenes, the LLM receives complete structured data as content blocks via the responseFormatter function. This includes:

• All metadata (commit hashes, timestamps, authors)

• Full file lists and change details (never truncated - LLMs need complete context)

• Structured JSON or formatted markdown based on configuration

• Everything needed to answer follow-up questions

Why This Matters: The LLM can answer detailed questions like "Who made the last commit?" or "What files changed in commit abc123?" because it has access to the full dataset, even if you only saw a summary.

Verbosity Levels: Control the amount of detail returned:

• Minimal: Core data only (success status, primary identifiers)

• Standard: Balanced output with essential context (recommended)

• Full: Complete data including all metadata and statistics

For Developers: When creating custom tools, always include complete data in your responseFormatter. Balance human-readable summaries with comprehensive structured information. See AGENTS.md for response formatter best practices and the MCP specification for technical details.

🧑‍💻 Agent Development Guide

For strict rules when using this server with an AI agent, refer to the AGENTS.md file in this repository. Key principles include:

• Logic Throws, Handlers Catch: Never use try/catch in your tool logic. Throw an McpError instead.

• Pass the Context: Always pass the RequestContext object through your call stack for logging and tracing.

• Use the Barrel Exports: Register new tools and resources only in the index.ts barrel files within their respective definitions directories.

• Declarative Tool Pattern: Each tool is defined in a single *.tool.ts file with schema, logic, and response formatting.

🔒 Security Features

• Path Sanitization: All file paths are validated and sanitized to prevent directory traversal attacks.

• Base Directory Restriction: Optional GIT_BASE_DIR configuration to restrict all git operations to a specific directory tree, providing security sandboxing for multi-tenant or shared hosting environments.

• Command Injection Prevention: Git commands are executed with carefully validated arguments via Bun.spawn.

• Destructive Operation Protection: Dangerous operations require explicit confirmation flags.

• Authentication Support: Built-in JWT and OAuth support for secure deployments.

• Rate Limiting: Optional rate limiting via the DI-managed RateLimiter service.

• Audit Logging: All Git operations are logged with full context for security auditing.

🧪 Testing

This server uses Vitest for testing.

• Run all tests:

  npm test

• Run tests with coverage:

  npm run test:coverage

• Run tests in watch mode:

  npm test -- --watch

🗺️ Roadmap

Planned Git Provider Integrations

The server uses a provider-based architecture to support multiple git implementation backends:

• ✅ CLI Provider (Current): Full-featured git operations via native git CLI

  • Complete coverage of all 27 git tools

  • Executes git commands using Bun.spawn for optimal performance

  • Streaming I/O handling for large outputs (10MB buffer limit)

  • Configurable timeouts (60s default) and automatic process cleanup

  • Requires local git installation

  • Best for local development and server deployments

• 🚧 Isomorphic Git Provider (Planned): Pure JavaScript git implementation

  • Edge deployment compatibility (Cloudflare Workers, Vercel Edge, Deno Deploy)

  • No system dependencies required

  • Enables true serverless git operations

  • Core operations: clone, status, add, commit, push, pull, branch, checkout

  • Implementation: isomorphic-git

• 💡 GitHub API Provider (Maybe): Cloud-native git operations via GitHub REST/GraphQL APIs

  • No local repository required

  • Direct integration with GitHub-hosted repositories

  • Ideal for GitHub-centric workflows

The provider system allows seamless switching between implementations based on deployment environment and requirements. See AGENTS.md for architectural details.

🤝 Contributing

Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.

Development Workflow

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes following the existing patterns

4. Run npm run devcheck to ensure code quality

5. Run npm test to verify all tests pass

6. Commit your changes with conventional commits

7. Push to your fork and open a Pull Request

📜 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.