Git MCP Server

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

Category Tools Description Repository Management git_init, git_clone, git_status, git_clean Initialize repos, clone from remotes, check status, clean untracked files Staging & Commits git_add, git_commit, git_diff Stage changes, create commits, compare changes History & Inspection git_log, git_show, git_blame, git_reflog View commit history, inspect objects, trace authorship, view ref logs Analysis git_changelog_analyze Gather git context and instructions for LLM-driven changelog analysis Branching & Merging git_branch, git_checkout, git_merge, git_rebase, git_cherry_pick Manage branches, switch contexts, integrate changes, apply specific commits Remote Operations git_remote, git_fetch, git_pull, git_push Configure remotes, fetch updates, synchronize repositories, publish changes Advanced Workflows git_tag, git_stash, git_reset, git_worktree, git_set_working_dir, git_clear_working_dir, git_wrapup_instructions Tag releases (list/create/delete/verify), stash changes, reset state, manage worktrees, set/clear session directory

Resources

Resource URI Description Git Working Directory git://working-directory The current session working directory, set via git_set_working_dir.

Prompts

Prompt Description Parameters Git Wrap-up Workflow protocol for completing git sessions: review, document, commit, and tag changes. changelogPath, createTag.

Features

Built on mcp-ts-template.

Feature Details Declarative tools Define capabilities in single, self-contained files. The framework handles registration, validation, and execution. Error handling Unified McpError system for consistent, structured error responses. Authentication Supports none, jwt, and oauth modes. Pluggable storage Swap backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic. Observability Structured logging (Pino) and optional auto-instrumented OpenTelemetry for traces and metrics. Dependency injection Built with tsyringe for decoupled, testable architecture. Cross-runtime Auto-detects Bun or Node.js and uses the appropriate process spawning method. Provider architecture Pluggable git provider system. Current: CLI. Planned: isomorphic-git for edge deployment. Working directory management Session-specific directory context for multi-repo workflows. Configurable git identity Override author/committer info via environment variables, with fallback to global git config. Commit signing GPG/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. Safety Destructive 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.

Project structure

Directory Purpose src/mcp-server/tools Tool definitions (*.tool.ts). Git capabilities live here. src/mcp-server/resources Resource definitions (*.resource.ts). Git context data sources. src/mcp-server/transports HTTP and STDIO transport implementations, including auth. src/storage StorageService abstraction and provider implementations. src/services Git service provider (CLI-based git operations). src/container DI container registrations and tokens. src/utils Logging, error handling, performance, security utilities. src/config Environment 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.

Built with the mcp-ts-template

Sponsor this project · Buy me a coffee

Getting started

Runtime

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

Runtime Command Minimum Version Node.js npx @cyanheads/git-mcp-server@latest >= 20.0.0 Bun bunx @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": "[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.

Configuration

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

Variable Description Default MCP_TRANSPORT_TYPE Transport: stdio or http. stdio MCP_SESSION_MODE HTTP session mode: stateless, stateful, or auto. auto MCP_RESPONSE_FORMAT Response format: json (LLM-optimized), markdown (human-readable), or auto. json MCP_RESPONSE_VERBOSITY Detail level: minimal, standard, or full. standard MCP_HTTP_PORT HTTP server port. 3015 MCP_HTTP_HOST HTTP server hostname. 127.0.0.1 MCP_HTTP_ENDPOINT_PATH MCP request endpoint path. /mcp MCP_AUTH_MODE Authentication mode: none, jwt, or oauth. none STORAGE_PROVIDER_TYPE Storage backend: in-memory, filesystem, supabase, cloudflare-kv, r2. in-memory OTEL_ENABLED Enable OpenTelemetry. false MCP_LOG_LEVEL Minimum log level: debug, info, warn, error. info GIT_SIGN_COMMITS GPG/SSH signing for commits, merges, rebases, cherry-picks, and tags. Falls back to unsigned on failure (see response signed/signingWarning). true GIT_AUTHOR_NAME Git author name. Aliases: GIT_USERNAME, GIT_USER. Falls back to global git config. (none) GIT_AUTHOR_EMAIL Git author email. Aliases: GIT_EMAIL, GIT_USER_EMAIL. Falls back to global git config. (none) GIT_BASE_DIR Absolute path to restrict all git operations to a specific directory tree. (none) GIT_WRAPUP_INSTRUCTIONS_PATH Path to custom markdown file with workflow instructions. (none) MCP_AUTH_SECRET_KEY Required for jwt auth. 32+ character secret key. (none) OAUTH_ISSUER_URL Required 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