🛠️ Tools Overview

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

📦 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 Bun (bunx)

{
  "mcpServers": {
    "git-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/git-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GIT_BASE_DIR": "~/Developer/",
        "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
        "GIT_USERNAME": "cyanheads",
        "GIT_EMAIL": "casey@caseyjhand.com",
        "GIT_SIGN_COMMITS": "false"
      }
    }
  }
}

Using Node.js (npx)

{
  "mcpServers": {
    "git-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GIT_BASE_DIR": "~/Developer/",
        "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
        "GIT_USERNAME": "cyanheads",
        "GIT_EMAIL": "casey@caseyjhand.com",
        "GIT_SIGN_COMMITS": "false"
      }
    }
  }
}

Streamable HTTP Configuration

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3015

✨ 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

• Either Bun v1.2.0+ OR Node.js v20.0.0+
• Git installed and accessible in your system PATH

Note: Development uses Bun for the best experience, but the published package works with both Bun (bunx) and Node.js (npx).

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/git-mcp-server.git

2. Navigate into the directory:

cd git-mcp-server

3. Install dependencies:

With Bun (recommended for development):

bun install

With Node.js:

npm install

⚙️ 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 bunx or npx (no installation required):

With Bun:

bunx @cyanheads/git-mcp-server@latest

With Node.js:

npx @cyanheads/git-mcp-server@latest

Both commands work identically and are configured through environment variables or your MCP client configuration.

Local Development

• Build and run the production version:

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

• Development mode with hot reload:

  bun dev:http
  # or
  bun dev:stdio

• Run checks and tests:

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

Cloudflare Workers

1. Build the Worker bundle:

bun build:worker

2. Run locally with Wrangler:

bun deploy:dev

3. Deploy to Cloudflare:

bun deploy:prod

📂 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:

# Git Status: main

## Staged (2)
- src/index.ts
- README.md

## Unstaged (1)
- package.json

JSON Format (LLM-Optimized):

{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}

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:

  bun test

• Run tests with coverage:

  bun test:coverage

• Run tests in watch mode:

  bun 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.

bun run devcheck
bun test

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 bun devcheck to ensure code quality
5. Run bun 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.