Skip to content
Back to search

git-mcp-server

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cyanheads--git-mcp-server/badge.svg)](/listings/cyanheads--git-mcp-server)

HTML

<a href="/listings/cyanheads--git-mcp-server"><img src="/api/listings/cyanheads--git-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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": "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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 256 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>@cyanheads/git-mcp-server</h1>
  3. <p><b>A Git MCP server for AI agents. STDIO & Streamable HTTP.</b>
  4. <div>28 Tools · 1 Resource · 1 Prompt</div>
  5. </p>
  6. </div>
  7. <div align="center">
  8. [![Version](https://img.shields.io/badge/Version-2.15.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.30.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/git-mcp-server/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
  9. </div>
  10. ---
  11. ## Tools
  12. 28 git operations organized into seven categories:
  13. | Category | Tools | Description |
  14. | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
  15. | **Repository Management** | `git_init`, `git_clone`, `git_status`, `git_clean` | Initialize repos, clone from remotes, check status, clean untracked files |
  16. | **Staging & Commits** | `git_add`, `git_commit`, `git_diff` | Stage changes, create commits, compare changes |
  17. | **History & Inspection** | `git_log`, `git_show`, `git_blame`, `git_reflog` | View commit history, inspect objects, trace authorship, view ref logs |
  18. | **Analysis** | `git_changelog_analyze` | Gather git context and instructions for LLM-driven changelog analysis |
  19. | **Branching & Merging** | `git_branch`, `git_checkout`, `git_merge`, `git_rebase`, `git_cherry_pick` | Manage branches, switch contexts, integrate changes, apply specific commits |
  20. | **Remote Operations** | `git_remote`, `git_fetch`, `git_pull`, `git_push` | Configure remotes, fetch updates, synchronize repositories, publish changes |
  21. | **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 |
  22. ## Resources
  23. | Resource | URI | Description |
  24. | :------------------------ | :------------------------ | :-------------------------------------------------------------------- |
  25. | **Git Working Directory** | `git://working-directory` | The current session working directory, set via `git_set_working_dir`. |
  26. ## Prompts
  27. | Prompt | Description | Parameters |
  28. | :-------------- | :---------------------------------------------------------------------------------------- | :---------------------------- |
  29. | **Git Wrap-up** | Workflow protocol for completing git sessions: review, document, commit, and tag changes. | `changelogPath`, `createTag`. |
  30. ## Getting started
  31. ### Runtime
  32. Works with both Bun and Node.js. Runtime is auto-detected.
  33. | Runtime | Command | Minimum Version |
  34. | ----------- | --------------------------------------- | --------------- |
  35. | **Node.js** | `npx @cyanheads/git-mcp-server@latest` | >= 20.0.0 |
  36. | **Bun** | `bunx @cyanheads/git-mcp-server@latest` | >= 1.2.0 |
  37. ### MCP client configuration
  38. 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.
  39. ```json
  40. {
  41. "mcpServers": {
  42. "git-mcp-server": {
  43. "type": "stdio",
  44. "command": "npx",
  45. "args": ["@cyanheads/git-mcp-server@latest"],
  46. "env": {
  47. "MCP_TRANSPORT_TYPE": "stdio",
  48. "MCP_LOG_LEVEL": "info",
  49. "GIT_BASE_DIR": "~/Developer/",
  50. "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
  51. "GIT_USERNAME": "cyanheads",
  52. "GIT_EMAIL": "casey@caseyjhand.com",
  53. "GIT_SIGN_COMMITS": "true"
  54. }
  55. }
  56. }
  57. }
  58. ```
  59. Bun users: replace `"command": "npx"` with `"command": "bunx"`.
  60. For Streamable HTTP, set `MCP_TRANSPORT_TYPE=http` and `MCP_HTTP_PORT=3015`.
  61. ## Features
  62. Built on [`mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template).
  63. | Feature | Details |
  64. | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  65. | Declarative tools | Define capabilities in single, self-contained files. The framework handles registration, validation, and execution. |
  66. | Error handling | Unified `McpError` system for consistent, structured error responses. |
  67. | Authentication | Supports `none`, `jwt`, and `oauth` modes. |
  68. | Pluggable storage | Swap backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic. |
  69. | Observability | Structured logging (Pino) and optional auto-instrumented OpenTelemetry for traces and metrics. |
  70. | Dependency injection | Built with `tsyringe` for decoupled, testable architecture. |
  71. | Cross-runtime | Auto-detects Bun or Node.js and uses the appropriate process spawning method. |
  72. | Provider architecture | Pluggable git provider system. Current: CLI. Planned: isomorphic-git for edge deployment. |
  73. | Working directory management | Session-specific directory context for multi-repo workflows. |
  74. | Configurable git identity | Override author/committer info via environment variables, with fallback to global git config. |
  75. | 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. |
  76. | Safety | Destructive operations (`git clean`, `git reset --hard`) require explicit confirmation flags. |
  77. ## Security
  78. - All file paths are validated and sanitized to prevent directory traversal.
  79. - Optional `GIT_BASE_DIR` restricts operations to a specific directory tree for multi-tenant sandboxing.
  80. - Git commands use validated arguments via process spawning — no shell interpolation.
  81. - JWT and OAuth support for authenticated deployments.
  82. - Optional rate limiting via the DI-managed `RateLimiter` service.
  83. - All operations are logged with request context for auditing.
  84. ## Configuration
  85. All configuration is validated at startup in `src/config/index.ts`. Key environment variables:
  86. | Variable | Description | Default |
  87. | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |
  88. | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
  89. | `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. | `auto` |
  90. | `MCP_RESPONSE_FORMAT` | Response format: `json` (LLM-optimized), `markdown` (human-readable), or `auto`. | `json` |
  91. | `MCP_RESPONSE_VERBOSITY` | Detail level: `minimal`, `standard`, or `full`. | `standard` |
  92. | `MCP_HTTP_PORT` | HTTP server port. | `3015` |
  93. | `MCP_HTTP_HOST` | HTTP server hostname. | `127.0.0.1` |
  94. | `MCP_HTTP_ENDPOINT_PATH` | MCP request endpoint path. | `/mcp` |
  95. | `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
  96. | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
  97. | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
  98. | `MCP_LOG_LEVEL` | Minimum log level: `debug`, `info`, `warn`, `error`. | `info` |
  99. | `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` |
  100. | `GIT_AUTHOR_NAME` | Git author name. Aliases: `GIT_USERNAME`, `GIT_USER`. Falls back to global git config. | `(none)` |
  101. | `GIT_AUTHOR_EMAIL` | Git author email. Aliases: `GIT_EMAIL`, `GIT_USER_EMAIL`. Falls back to global git config. | `(none)` |
  102. | `GIT_BASE_DIR` | Absolute path to restrict all git operations to a specific directory tree. | `(none)` |
  103. | `GIT_WRAPUP_INSTRUCTIONS_PATH` | Path to custom markdown file with workflow instructions. | `(none)` |
  104. | `MCP_AUTH_SECRET_KEY` | Required for `jwt` auth. 32+ character secret key. | `(none)` |
  105. | `OAUTH_ISSUER_URL` | Required for `oauth` auth. OIDC provider URL. | `(none)` |
  106. ## Running the server
  107. ### Via package manager (no install)
  108. ```sh
  109. npx @cyanheads/git-mcp-server@latest
  110. ```
  111. Configure through environment variables or your MCP client config.
  112. ### Local development
  113. ```sh
  114. # Build and run
  115. npm run rebuild
  116. npm run start:stdio # or start:http
  117. # Dev mode with hot reload
  118. npm run dev:stdio # or dev:http
  119. # Checks and tests
  120. npm run devcheck # lint, format, typecheck
  121. npm test
  122. ```
  123. ### Cloudflare Workers
  124. ```sh
  125. npm run build:worker # Build the worker bundle
  126. npm run deploy:dev # Run locally with Wrangler
  127. npm run deploy:prod # Deploy to Cloudflare
  128. ```
  129. ## Project structure
  130. | Directory | Purpose |
  131. | :-------------------------- | :---------------------------------------------------------------- |
  132. | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Git capabilities live here. |
  133. | `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Git context data sources. |
  134. | `src/mcp-server/transports` | HTTP and STDIO transport implementations, including auth. |
  135. | `src/storage` | `StorageService` abstraction and provider implementations. |
  136. | `src/services` | Git service provider (CLI-based git operations). |
  137. | `src/container` | DI container registrations and tokens. |
  138. | `src/utils` | Logging, error handling, performance, security utilities. |
  139. | `src/config` | Environment variable parsing and validation (Zod). |
  140. | `tests/` | Unit and integration tests, mirroring `src/` structure. |
  141. ## Response format
  142. Configure output format and verbosity via `MCP_RESPONSE_FORMAT` and `MCP_RESPONSE_VERBOSITY`.
  143. JSON format (default, optimized for LLM consumption):
  144. ```json
  145. {
  146. "success": true,
  147. "branch": "main",
  148. "staged": ["src/index.ts", "README.md"],
  149. "unstaged": ["package.json"],
  150. "untracked": []
  151. }
  152. ```
  153. Markdown format (human-readable):
  154. ```
  155. # Git Status: main
  156. ## Staged (2)
  157. - src/index.ts
  158. - README.md
  159. ## Unstaged (1)
  160. - package.json
  161. ```
  162. 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).
  163. ## Development guide
  164. See [`AGENTS.md`](AGENTS.md) for architecture, tool development patterns, and contribution rules.
  165. ## Testing
  166. Tests use [Bun's test runner](https://bun.sh/docs/cli/test) with Vitest compatibility.
  167. ```sh
  168. bun test # Run all tests
  169. bun test --coverage # With coverage
  170. bun run devcheck # Lint, format, typecheck, audit
  171. ```
  172. ## Roadmap
  173. The server uses a provider-based architecture for git operations:
  174. - **CLI provider** (current) — Full 28-tool coverage via native git CLI. Requires local git installation.
  175. - **Isomorphic git provider** (planned) — Pure JS implementation for edge deployment (Cloudflare Workers, Vercel Edge, Deno Deploy). Uses [isomorphic-git](https://isomorphic-git.org/).
  176. - **GitHub API provider** (maybe) — Cloud-native operations via GitHub REST/GraphQL APIs, no local repo required.
  177. ## Contributing
  178. Issues and pull requests are welcome. Run checks before submitting:
  179. ```sh
  180. npm run devcheck
  181. npm test
  182. ```
  183. ## License
  184. Apache 2.0. See [LICENSE](./LICENSE).
  185. ---
  186. <div align="center">
  187. <p>Built with the <a href="https://github.com/cyanheads/mcp-ts-template">mcp-ts-template</a></p>
  188. <p>
  189. <a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> ·
  190. <a href="https://www.buymeacoffee.com/cyanheads">Buy me a coffee</a>
  191. </p>
  192. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.