io.github.cyanheads/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:

Resources

Prompts

Getting started

Runtime

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

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.

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:

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

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