{ "markdown": "
\n

@cyanheads/git-mcp-server

\n

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

28 Tools · 1 Resource · 1 Prompt
\n

\n
\n\n
\n\n[![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/)\n\n
\n\n---\n\n## Tools\n\n28 git operations organized into seven categories:\n\n| Category | Tools | Description |\n| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |\n| **Repository Management** | `git_init`, `git_clone`, `git_status`, `git_clean` | Initialize repos, clone from remotes, check status, clean untracked files |\n| **Staging & Commits** | `git_add`, `git_commit`, `git_diff` | Stage changes, create commits, compare changes |\n| **History & Inspection** | `git_log`, `git_show`, `git_blame`, `git_reflog` | View commit history, inspect objects, trace authorship, view ref logs |\n| **Analysis** | `git_changelog_analyze` | Gather git context and instructions for LLM-driven changelog analysis |\n| **Branching & Merging** | `git_branch`, `git_checkout`, `git_merge`, `git_rebase`, `git_cherry_pick` | Manage branches, switch contexts, integrate changes, apply specific commits |\n| **Remote Operations** | `git_remote`, `git_fetch`, `git_pull`, `git_push` | Configure remotes, fetch updates, synchronize repositories, publish changes |\n| **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 |\n\n## Resources\n\n| Resource | URI | Description |\n| :------------------------ | :------------------------ | :-------------------------------------------------------------------- |\n| **Git Working Directory** | `git://working-directory` | The current session working directory, set via `git_set_working_dir`. |\n\n## Prompts\n\n| Prompt | Description | Parameters |\n| :-------------- | :---------------------------------------------------------------------------------------- | :---------------------------- |\n| **Git Wrap-up** | Workflow protocol for completing git sessions: review, document, commit, and tag changes. | `changelogPath`, `createTag`. |\n\n## Getting started\n\n### Runtime\n\nWorks with both Bun and Node.js. Runtime is auto-detected.\n\n| Runtime | Command | Minimum Version |\n| ----------- | --------------------------------------- | --------------- |\n| **Node.js** | `npx @cyanheads/git-mcp-server@latest` | >= 20.0.0 |\n| **Bun** | `bunx @cyanheads/git-mcp-server@latest` | >= 1.2.0 |\n\n### MCP client configuration\n\nAdd 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.\n\n```json\n{\n \"mcpServers\": {\n \"git-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"@cyanheads/git-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"GIT_BASE_DIR\": \"~/Developer/\",\n \"LOGS_DIR\": \"~/Developer/logs/git-mcp-server/\",\n \"GIT_USERNAME\": \"cyanheads\",\n \"GIT_EMAIL\": \"casey@caseyjhand.com\",\n \"GIT_SIGN_COMMITS\": \"true\"\n }\n }\n }\n}\n```\n\nBun users: replace `\"command\": \"npx\"` with `\"command\": \"bunx\"`.\n\nFor Streamable HTTP, set `MCP_TRANSPORT_TYPE=http` and `MCP_HTTP_PORT=3015`.\n\n## Features\n\nBuilt on [`mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template).\n\n| Feature | Details |\n| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Declarative tools | Define capabilities in single, self-contained files. The framework handles registration, validation, and execution. |\n| Error handling | Unified `McpError` system for consistent, structured error responses. |\n| Authentication | Supports `none`, `jwt`, and `oauth` modes. |\n| Pluggable storage | Swap backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic. |\n| Observability | Structured logging (Pino) and optional auto-instrumented OpenTelemetry for traces and metrics. |\n| Dependency injection | Built with `tsyringe` for decoupled, testable architecture. |\n| Cross-runtime | Auto-detects Bun or Node.js and uses the appropriate process spawning method. |\n| Provider architecture | Pluggable git provider system. Current: CLI. Planned: isomorphic-git for edge deployment. |\n| Working directory management | Session-specific directory context for multi-repo workflows. |\n| Configurable git identity | Override author/committer info via environment variables, with fallback to global git config. |\n| 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. |\n| Safety | Destructive operations (`git clean`, `git reset --hard`) require explicit confirmation flags. |\n\n## Security\n\n- All file paths are validated and sanitized to prevent directory traversal.\n- Optional `GIT_BASE_DIR` restricts operations to a specific directory tree for multi-tenant sandboxing.\n- Git commands use validated arguments via process spawning — no shell interpolation.\n- JWT and OAuth support for authenticated deployments.\n- Optional rate limiting via the DI-managed `RateLimiter` service.\n- All operations are logged with request context for auditing.\n\n## Configuration\n\nAll configuration is validated at startup in `src/config/index.ts`. Key environment variables:\n\n| Variable | Description | Default |\n| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. | `auto` |\n| `MCP_RESPONSE_FORMAT` | Response format: `json` (LLM-optimized), `markdown` (human-readable), or `auto`. | `json` |\n| `MCP_RESPONSE_VERBOSITY` | Detail level: `minimal`, `standard`, or `full`. | `standard` |\n| `MCP_HTTP_PORT` | HTTP server port. | `3015` |\n| `MCP_HTTP_HOST` | HTTP server hostname. | `127.0.0.1` |\n| `MCP_HTTP_ENDPOINT_PATH` | MCP request endpoint path. | `/mcp` |\n| `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |\n| `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |\n| `MCP_LOG_LEVEL` | Minimum log level: `debug`, `info`, `warn`, `error`. | `info` |\n| `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` |\n| `GIT_AUTHOR_NAME` | Git author name. Aliases: `GIT_USERNAME`, `GIT_USER`. Falls back to global git config. | `(none)` |\n| `GIT_AUTHOR_EMAIL` | Git author email. Aliases: `GIT_EMAIL`, `GIT_USER_EMAIL`. Falls back to global git config. | `(none)` |\n| `GIT_BASE_DIR` | Absolute path to restrict all git operations to a specific directory tree. | `(none)` |\n| `GIT_WRAPUP_INSTRUCTIONS_PATH` | Path to custom markdown file with workflow instructions. | `(none)` |\n| `MCP_AUTH_SECRET_KEY` | Required for `jwt` auth. 32+ character secret key. | `(none)` |\n| `OAUTH_ISSUER_URL` | Required for `oauth` auth. OIDC provider URL. | `(none)` |\n\n## Running the server\n\n### Via package manager (no install)\n\n```sh\nnpx @cyanheads/git-mcp-server@latest\n```\n\nConfigure through environment variables or your MCP client config.\n\n### Local development\n\n```sh\n# Build and run\nnpm run rebuild\nnpm run start:stdio # or start:http\n\n# Dev mode with hot reload\nnpm run dev:stdio # or dev:http\n\n# Checks and tests\nnpm run devcheck # lint, format, typecheck\nnpm test\n```\n\n### Cloudflare Workers\n\n```sh\nnpm run build:worker # Build the worker bundle\nnpm run deploy:dev # Run locally with Wrangler\nnpm run deploy:prod # Deploy to Cloudflare\n```\n\n## Project structure\n\n| Directory | Purpose |\n| :-------------------------- | :---------------------------------------------------------------- |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Git capabilities live here. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Git context data sources. |\n| `src/mcp-server/transports` | HTTP and STDIO transport implementations, including auth. |\n| `src/storage` | `StorageService` abstraction and provider implementations. |\n| `src/services` | Git service provider (CLI-based git operations). |\n| `src/container` | DI container registrations and tokens. |\n| `src/utils` | Logging, error handling, performance, security utilities. |\n| `src/config` | Environment variable parsing and validation (Zod). |\n| `tests/` | Unit and integration tests, mirroring `src/` structure. |\n\n## Response format\n\nConfigure output format and verbosity via `MCP_RESPONSE_FORMAT` and `MCP_RESPONSE_VERBOSITY`.\n\nJSON format (default, optimized for LLM consumption):\n\n```json\n{\n \"success\": true,\n \"branch\": \"main\",\n \"staged\": [\"src/index.ts\", \"README.md\"],\n \"unstaged\": [\"package.json\"],\n \"untracked\": []\n}\n```\n\nMarkdown format (human-readable):\n\n```\n# Git Status: main\n\n## Staged (2)\n- src/index.ts\n- README.md\n\n## Unstaged (1)\n- package.json\n```\n\nThe 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).\n\n## Development guide\n\nSee [`AGENTS.md`](AGENTS.md) for architecture, tool development patterns, and contribution rules.\n\n## Testing\n\nTests use [Bun's test runner](https://bun.sh/docs/cli/test) with Vitest compatibility.\n\n```sh\nbun test # Run all tests\nbun test --coverage # With coverage\nbun run devcheck # Lint, format, typecheck, audit\n```\n\n## Roadmap\n\nThe server uses a provider-based architecture for git operations:\n\n- **CLI provider** (current) — Full 28-tool coverage via native git CLI. Requires local git installation.\n- **Isomorphic git provider** (planned) — Pure JS implementation for edge deployment (Cloudflare Workers, Vercel Edge, Deno Deploy). Uses [isomorphic-git](https://isomorphic-git.org/).\n- **GitHub API provider** (maybe) — Cloud-native operations via GitHub REST/GraphQL APIs, no local repo required.\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks before submitting:\n\n```sh\nnpm run devcheck\nnpm test\n```\n\n## License\n\nApache 2.0. See [LICENSE](./LICENSE).\n\n---\n\n
\n

Built with the mcp-ts-template

\n

\n Sponsor this project ·\n Buy me a coffee\n

\n
\n", "bytes": 17194, "sha": "5c5ab87541db9eb941521af4e1ecb316018e49ca099d40f795ed40e89e5e8e10", "repo_slug": "cyanheads/git-mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_git_mcp_server_cbb37f36/readme" }