PluginBench
MCP Server
Maintained
Apache-2.0

io.github.cyanheads/git-mcp-server MCP Server

io.github.cyanheads/git-mcp-server

Comprehensive Git MCP server with 28 tools for AI agents to clone, commit, branch, merge, and manage repositories.

RepositoryRegistry
How to choose

What this kind of tool is for

  • Automate a build, test, or deployment step you repeat by hand.
  • Review or refactor code in an existing repository without leaving your agent.
  • Bridge an internal service or CLI into the agent toolset.

How to compare servers like this

Scope of control:
Repos and CI are hard to undo; prefer tools that ask before anything irreversible.
Environment fit:
Match the runtime it expects (Node, Python, a container) to what you actually run.
Maintenance signal:
Check the last-commit date — dev tooling that lags upstream breaks first.
Config surface:
Prefer tools whose environment-variable or config keys are documented plainly.

This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.

What is the io.github.cyanheads/git-mcp-server MCP server?

The @cyanheads/git-mcp-server is a Git MCP server that exposes 28 native git operations to AI agents via STDIO and HTTP transports. It enables full repository management including cloning, committing, branching, merging, and advanced workflows like worktrees and cherry-picking, with built-in support for GPG/SSH signing, multi-repo sessions, and configurable git identity.

This server gives AI agents like Claude and Cursor direct access to comprehensive git operations. It supports repository initialization and cloning, staging and committing changes, branch management, history inspection, remote synchronization, and advanced workflows. With features like commit signing, working directory management, and safety confirmations for destructive operations, it's designed for AI-driven development workflows that need full version control capabilities.

How to install io.github.cyanheads/git-mcp-server

Copy-paste configuration for popular MCP clients.

transport: stdio
Config generated by PluginBench — verify against the source before use.
Environment / auth
  • MCP_LOG_LEVEL

    Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

  • GIT_BASE_DIR

    Optional absolute path to restrict all git operations to a specific directory tree. Provides security sandboxing for multi-tenant or shared environments.

  • MCP_HTTP_HOST

    The hostname for the HTTP server.

  • MCP_HTTP_PORT

    The port to run the HTTP server on.

  • MCP_HTTP_ENDPOINT_PATH

    The endpoint path for the MCP server.

  • MCP_AUTH_MODE

    Authentication mode to use: 'none', 'jwt', or 'oauth'.

~/Library/Application Support/Claude/claude_desktop_config.json
JSON config
{
  "mcpServers": {
    "git-mcp-server": {
      "command": "bun",
      "args": [
        "-y",
        "@cyanheads/git-mcp-server",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "<YOUR_MCP_LOG_LEVEL>",
        "GIT_BASE_DIR": "<YOUR_GIT_BASE_DIR>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_ENDPOINT_PATH": "<YOUR_MCP_HTTP_ENDPOINT_PATH>",
        "MCP_AUTH_MODE": "<YOUR_MCP_AUTH_MODE>"
      }
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

  • git_init — Initialize a new git repository
  • git_clone — Clone a repository from a remote
  • git_status — Check repository status
  • git_clean — Clean untracked files
  • git_add — Stage changes for commit
  • git_commit — Create a commit
  • git_diff — Compare changes between versions
  • git_log — View commit history
  • git_show — Inspect git objects
  • git_blame — Trace authorship of lines
  • git_reflog — View reference logs
  • git_changelog_analyze — Gather git context and instructions for LLM-driven changelog analysis
  • git_branch — Manage branches
  • git_checkout — Switch branches or contexts
  • git_merge — Integrate changes from one branch to another
  • git_rebase — Reapply commits on top of another branch
  • git_cherry_pick — Apply specific commits to current branch
  • git_remote — Configure remote repositories
  • git_fetch — Fetch updates from remotes
  • git_pull — Synchronize repositories

Use cases

  • Clone repositories and manage multiple branches for AI-assisted development workflows
  • Automate commit creation with proper git identity and GPG/SSH signing for secure version control
  • Analyze commit history and generate changelogs using LLM-driven changelog analysis
  • Manage complex workflows using worktrees, cherry-picks, and rebases for multi-feature development
  • Review and inspect code changes with diff, blame, and log tools before committing

io.github.cyanheads/git-mcp-server MCP server FAQ

What is the git-mcp-server?

It's an MCP server that exposes 28 git operations to AI agents, enabling full repository management including cloning, committing, branching, merging, and advanced workflows through STDIO or HTTP transports.

Is it free?

Yes, the git-mcp-server is open-source under the Apache 2.0 license and available via npm as @cyanheads/git-mcp-server.

How do I install it in Cursor or Claude?

Add it to your MCP client config (e.g., cline_mcp_settings.json) with command 'npx @cyanheads/git-mcp-server@latest' or 'bunx @cyanheads/git-mcp-server@latest' for Bun, setting environment variables like GIT_USERNAME and GIT_EMAIL.

Does it require authentication?

No authentication is required by default (auth_mode: none), but it supports optional JWT and OAuth modes for authenticated deployments.

Does it support commit signing?

Yes, it supports GPG/SSH signing for commits, merges, rebases, cherry-picks, and tags via the GIT_SIGN_COMMITS environment variable, with automatic fallback to unsigned commits if signing fails.

What are the runtime requirements?

It works with Node.js >= 20.0.0 or Bun >= 1.2.0, with auto-detection of the runtime. Configuration is done via environment variables like GIT_BASE_DIR, GIT_USERNAME, and GIT_EMAIL.

README (reference)

Source of truth, from the repository.

<div align="center"> <h1>@cyanheads/git-mcp-server</h1> <p><b>A Git MCP server for AI agents. STDIO & Streamable HTTP.</b> <div>28 Tools · 1 Resource · 1 Prompt</div> </p> </div> <div align="center">

Version MCP Spec MCP SDK License Status TypeScript Bun

</div>

Tools

28 git operations organized into seven categories:

CategoryToolsDescription
Repository Managementgit_init, git_clone, git_status, git_cleanInitialize repos, clone from remotes, check status, clean untracked files
Staging & Commitsgit_add, git_commit, git_diffStage changes, create commits, compare changes
History & Inspectiongit_log, git_show, git_blame, git_reflogView commit history, inspect objects, trace authorship, view ref logs
Analysisgit_changelog_analyzeGather git context and instructions for LLM-driven changelog analysis
Branching & Merginggit_branch, git_checkout, git_merge, git_rebase, git_cherry_pickManage branches, switch contexts, integrate changes, apply specific commits
Remote Operationsgit_remote, git_fetch, git_pull, git_pushConfigure remotes, fetch updates, synchronize repositories, publish changes
Advanced Workflowsgit_tag, git_stash, git_reset, git_worktree, git_set_working_dir, git_clear_working_dir, git_wrapup_instructionsTag releases (list/create/delete/verify), stash changes, reset state, manage worktrees, set/clear session directory

Resources

ResourceURIDescription
Git Working Directorygit://working-directoryThe current session working directory, set via git_set_working_dir.

Prompts

PromptDescriptionParameters
Git Wrap-upWorkflow protocol for completing git sessions: review, document, commit, and tag changes.changelogPath, createTag.

Getting started

Runtime

Works with both Bun and Node.js. Runtime is auto-detected.

RuntimeCommandMinimum Version
Node.jsnpx @cyanheads/git-mcp-server@latest>= 20.0.0
Bunbunx @cyanheads/git-mcp-server@latest>= 1.2.0

MCP client configuration

Add the following to your MCP client config (e.g., cline_mcp_settings.json). Update the environment variables to match your setup — especially the git identity fields.

{
  "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": "true"
      }
    }
  }
}

Bun users: replace "command": "npx" with "command": "bunx".

For Streamable HTTP, set MCP_TRANSPORT_TYPE=http and MCP_HTTP_PORT=3015.

Features

Built on mcp-ts-template.

FeatureDetails
Declarative toolsDefine capabilities in single, self-contained files. The framework handles registration, validation, and execution.
Error handlingUnified McpError system for consistent, structured error responses.
AuthenticationSupports none, jwt, and oauth modes.
Pluggable storageSwap backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic.
ObservabilityStructured logging (Pino) and optional auto-instrumented OpenTelemetry for traces and metrics.
Dependency injectionBuilt with tsyringe for decoupled, testable architecture.
Cross-runtimeAuto-detects Bun or Node.js and uses the appropriate process spawning method.
Provider architecturePluggable git provider system. Current: CLI. Planned: isomorphic-git for edge deployment.
Working directory managementSession-specific directory context for multi-repo workflows.
Configurable git identityOverride author/committer info via environment variables, with fallback to global git config.
Commit signingGPG/SSH signing (enabled by default) for commits, merges, rebases, cherry-picks, and tags. Silent fallback to unsigned on failure with signed/signingWarning fields in responses.
SafetyDestructive operations (git clean, git reset --hard) require explicit confirmation flags.

Security

  • All file paths are validated and sanitized to prevent directory traversal.
  • Optional GIT_BASE_DIR restricts operations to a specific directory tree for multi-tenant sandboxing.
  • Git commands use validated arguments via process spawning — no shell interpolation.
  • JWT and OAuth support for authenticated deployments.
  • Optional rate limiting via the DI-managed RateLimiter service.
  • All operations are logged with request context for auditing.

Configuration

All configuration is validated at startup in src/config/index.ts. Key environment variables:

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto.auto
MCP_RESPONSE_FORMATResponse format: json (LLM-optimized), markdown (human-readable), or auto.json
MCP_RESPONSE_VERBOSITYDetail level: minimal, standard, or full.standard
MCP_HTTP_PORTHTTP server port.3015
MCP_HTTP_HOSTHTTP server hostname.127.0.0.1
MCP_HTTP_ENDPOINT_PATHMCP request endpoint path./mcp
MCP_AUTH_MODEAuthentication mode: none, jwt, or oauth.none
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv, r2.in-memory
OTEL_ENABLEDEnable OpenTelemetry.false
MCP_LOG_LEVELMinimum log level: debug, info, warn, error.info
GIT_SIGN_COMMITSGPG/SSH signing for commits, merges, rebases, cherry-picks, and tags. Falls back to unsigned on failure (see response signed/signingWarning).true
GIT_AUTHOR_NAMEGit author name. Aliases: GIT_USERNAME, GIT_USER. Falls back to global git config.(none)
GIT_AUTHOR_EMAILGit author email. Aliases: GIT_EMAIL, GIT_USER_EMAIL. Falls back to global git config.(none)
GIT_BASE_DIRAbsolute path to restrict all git operations to a specific directory tree.(none)
GIT_WRAPUP_INSTRUCTIONS_PATHPath to custom markdown file with workflow instructions.(none)
MCP_AUTH_SECRET_KEYRequired for jwt auth. 32+ character secret key.(none)
OAUTH_ISSUER_URLRequired for oauth auth. OIDC provider URL.(none)

Running the server

Via package manager (no install)

npx @cyanheads/git-mcp-server@latest

Configure through environment variables or your MCP client config.

Local development

# Build and run
npm run rebuild
npm run start:stdio   # or start:http

# Dev mode with hot reload
npm run dev:stdio     # or dev:http

# Checks and tests
npm run devcheck      # lint, format, typecheck
npm test

Cloudflare Workers

npm run build:worker   # Build the worker bundle
npm run deploy:dev     # Run locally with Wrangler
npm run deploy:prod    # Deploy to Cloudflare

Project structure

DirectoryPurpose
src/mcp-server/toolsTool definitions (*.tool.ts). Git capabilities live here.
src/mcp-server/resourcesResource definitions (*.resource.ts). Git context data sources.
src/mcp-server/transportsHTTP and STDIO transport implementations, including auth.
src/storageStorageService abstraction and provider implementations.
src/servicesGit service provider (CLI-based git operations).
src/containerDI container registrations and tokens.
src/utilsLogging, error handling, performance, security utilities.
src/configEnvironment variable parsing and validation (Zod).
tests/Unit and integration tests, mirroring src/ structure.

Response format

Configure output format and verbosity via MCP_RESPONSE_FORMAT and MCP_RESPONSE_VERBOSITY.

JSON format (default, optimized for LLM consumption):

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

Markdown format (human-readable):

# Git Status: main

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

## Unstaged (1)
- package.json

The LLM always receives the complete structured data via responseFormatter — full file lists, metadata, timestamps — regardless of what the client displays. Verbosity controls how much detail is included: minimal (core fields only), standard (balanced), or full (everything).

Development guide

See AGENTS.md for architecture, tool development patterns, and contribution rules.

Testing

Tests use Bun's test runner with Vitest compatibility.

bun test              # Run all tests
bun test --coverage   # With coverage
bun run devcheck      # Lint, format, typecheck, audit

Roadmap

The server uses a provider-based architecture for git operations:

  • CLI provider (current) — Full 28-tool coverage via native git CLI. Requires local git installation.
  • Isomorphic git provider (planned) — Pure JS implementation for edge deployment (Cloudflare Workers, Vercel Edge, Deno Deploy). Uses isomorphic-git.
  • GitHub API provider (maybe) — Cloud-native operations via GitHub REST/GraphQL APIs, no local repo required.

Contributing

Issues and pull requests are welcome. Run checks before submitting:

npm run devcheck
npm test

License

Apache 2.0. See LICENSE.


<div align="center"> <p>Built with the <a href="https://github.com/cyanheads/mcp-ts-template">mcp-ts-template</a></p> <p> <a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> · <a href="https://www.buymeacoffee.com/cyanheads">Buy me a coffee</a> </p> </div>

Related MCP servers

Look up allele frequencies by ancestry, gene constraint, variants, and coverage over gnomAD.

1
TypeScript
Apache-2.0
View repository →

Search Grants.gov funding opportunities and read full records: eligibility, awards, deadlines.

1
TypeScript
Apache-2.0
View repository →

Guardian Open Platform — search and retrieve full article text from The Guardian archive.

2
TypeScript
Apache-2.0
View repository →

MCP server for Project Gutenberg — 75,000+ public-domain ebooks with full plain-text retrieval.

2
TypeScript
Apache-2.0
View repository →

Browse Hacker News feeds, threads, and user profiles with full-text search.

4
TypeScript
Apache-2.0
View repository →

Search ILOSTAT labour indicators, query and compare series, build country profiles, run SQL.

1
TypeScript
Apache-2.0
View repository →