Git Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv2.15.3Updated Oct 24, 2026

Comprehensive Git MCP server enabling native git tools including clone, commit, worktree, & more.

VerifiedSTDIODesktop onlyFiles & StorageDeveloper Tools

Overview

AI-generated overview

A local Git MCP server that gives an AI assistant 28 native git tools to clone, commit, branch, merge, push, and inspect repositories.

What you can do
Initialize, clone, check status and clean repositories, and set or clear the session working directory for multi-repo work. Stage changes, create commits, and compare diffs. Read history and inspect objects: log, show, blame, reflog, plus a changelog analysis helper. Manage branches, checkout, merge, rebase, and cherry-pick. Configure remotes, fetch, pull, and push. Tag, stash, reset, and manage worktrees, with a wrap-up prompt for reviewing and committing a session.
When to use it
Useful when you want an assistant to work directly with local Git repositories: reviewing changes, writing commits, managing branches, or syncing with remotes without you running each command by hand.
Requirements
Runs locally via npx (Node.js 20 or newer) or bunx (Bun 1.2 or newer). Optional environment variables configure the git identity, a base directory, commit signing, logging, and HTTP transport with optional jwt or oauth authentication.
Before you install
It can write to repositories: commits, merges, rebases, cherry-picks, pushes, tags, stashes, and resets. Destructive operations such as clean and hard reset require explicit confirmation flags. Commit signing is on by default and silently falls back to unsigned on failure. Restrict scope with GIT_BASE_DIR, and note that jwt auth needs MCP_AUTH_SECRET_KEY.

Installation

In SourceWeft

  1. Open Git Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@cyanheads/git-mcp-server

A Git MCP server for AI agents. STDIO & Streamable HTTP.

28 Tools · 1 Resource · 1 Prompt

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.

json
{  "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": "[email protected]",        "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)

sh
npx @cyanheads/git-mcp-server@latest

Configure through environment variables or your MCP client config.

Local development

sh
# Build and runnpm run rebuildnpm run start:stdio   # or start:http
# Dev mode with hot reloadnpm run dev:stdio     # or dev:http
# Checks and testsnpm run devcheck      # lint, format, typechecknpm test

Cloudflare Workers

sh
npm run build:worker   # Build the worker bundlenpm run deploy:dev     # Run locally with Wranglernpm 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):

json
{  "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.

sh
bun test              # Run all testsbun test --coverage   # With coveragebun 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:

sh
npm run devchecknpm test

License

Apache 2.0. See LICENSE.

Source: README.md at commit d34d83a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v2.15.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts