⚙

Git MCP 服务器

一个为AI代理设计的Git MCP服务器，支持STDIO和可流式HTTP传输。

作者 By cyanheads

本地部署 Git操作 AI代理

GitHub

@cyanheads/git-mcp-server

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

28 Tools · 1 Resource · 1 Prompt

工具

28个git操作分为七类：

类别	工具	描述
库管理	`git_init`, `git_clone`, `git_status`, `git_clean`	初始化存储库、从远程克隆、检查状态、清理未跟踪的文件
分期付款和承诺	`git_add`, `git_commit`, `git_diff`	阶段更改、创建提交、比较更改
历史与检查	`git_log`, `git_show`, `git_blame`, `git_reflog`	查看提交历史、检查对象、跟踪作者、查看引用日志
分析	`git_changelog_analyze`	收集git上下文和指令，用于LLM驱动的变更日志分析
分支与合并	`git_branch`, `git_checkout`, `git_merge`, `git_rebase`, `git_cherry_pick`	管理分支、切换上下文、集成更改、应用特定提交
远程操作	`git_remote`, `git_fetch`, `git_pull`, `git_push`	配置遥控器、获取更新、同步存储库、发布更改
高级工作流	`git_tag`, `git_stash`, `git_reset`, `git_worktree`, `git_set_working_dir`, `git_clear_working_dir`, `git_wrapup_instructions`	标记释放、隐藏更改、重置状态、管理工作树、设置/清除会话目录

资源

资源	URI	描述
Git工作目录	`git://working-directory`	当前会话工作目录，通过设置 `git_set_working_dir`.

提示

提示	说明	参数
Git总结	完成git会话的工作流协议：审查、记录、提交和标记更改。	`changelogPath`, `skipDocumentation`, `createTag`, `updateAgentFiles`.

入门

运行时

适用于Bun和Node.js。自动检测运行时间。

运行时	命令	最低版本
Node.js	`npx @cyanheads/git-mcp-server@latest`	>= 20.0.0
包子	`bunx @cyanheads/git-mcp-server@latest`	>= 1.2.0

MCP客户端配置

将以下内容添加到MCP客户端配置中（例如。， cline_mcp_settings.json).更新环境变量以匹配您的设置，尤其是git标识字段。

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18{ “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用户：更换 `"command": "npx"` 和 `"command": "bunx"`.


对于流式HTTP，设置 `MCP_TRANSPORT_TYPE=http` 和 `MCP_HTTP_PORT=3015`.


## 特性


建立在 [`mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template).


| 功能 | 详细信息 |
| --- | --- |
| 声明性工具 | 在单个自包含的文件中定义功能。该框架处理注册、验证和执行。 |
| 错误处理 | 统一 `McpError` 用于一致、结构化错误响应的系统。 |
| 身份验证 | 支持 `none`, `jwt`，以及 `oauth` 模式。 |
| 可插拔存储 | 交换后端(`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`)而不改变业务逻辑。 |
| 可观察性 | 结构化日志记录（Pino）和可选的自动仪器化OpenTetry用于跟踪和度量。 |
| 依赖注入 | 内置 `tsyringe` 用于解耦、可测试的架构。 |
| 跨运行时 | 自动检测Bun或Node.js，并使用适当的进程生成方法。 |
| 提供者架构 | 可插拔的git提供者系统。当前版本：CLI。计划：同构git用于边缘部署。 |
| 工作目录管理 | 多仓库工作流的会话特定目录上下文。 |
| 可配置的git标识 | 通过环境变量覆盖作者/提交者信息，并回退到全局git配置。 |
| 提交签名 | 可选的GPG/SSH签名，用于提交、合并、重基、樱桃挑选和标记。 |
| 安全 | 破坏性操作(`git clean`, `git reset --hard`)需要明确的确认标志。 |


## 安全


- 所有文件路径都经过验证和清理，以防止目录遍历。
- 可选的 `GIT_BASE_DIR` 将操作限制在多租户沙盒的特定目录树中。
- Git命令通过进程生成使用经过验证的参数——没有shell插值。
- JWT和OAuth支持经过身份验证的部署。
- 通过DI管理的可选速率限制 `RateLimiter` 服务。
- 所有操作都会记录请求上下文以供审核。


## 配置


所有配置在启动时均已验证 `src/config/index.ts`.关键环境变量：


| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `MCP_TRANSPORT_TYPE` | 运输： `stdio` 或 `http`. | `stdio` |
| `MCP_SESSION_MODE` | HTTP会话模式： `stateless`, `stateful`，或 `auto`. | `auto` |
| `MCP_RESPONSE_FORMAT` | 响应格式： `json` （LLM优化）， `markdown` （人类可读），或 `auto`. | `json` |
| `MCP_RESPONSE_VERBOSITY` | 细节级别： `minimal`, `standard`，或 `full`. | `standard` |
| `MCP_HTTP_PORT` | HTTP服务器端口 | `3015` |
| `MCP_HTTP_HOST` | HTTP服务器主机名。 | `127.0.0.1` |
| `MCP_HTTP_ENDPOINT_PATH` | MCP请求端点路径。 | `/mcp` |
| `MCP_AUTH_MODE` | 身份验证模式： `none`, `jwt`，或 `oauth`. | `none` |
| `STORAGE_PROVIDER_TYPE` | 存储后端： `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
| `OTEL_ENABLED` | 启用OpenTetry。 | `false` |
| `MCP_LOG_LEVEL` | 最低日志级别： `debug`, `info`, `warn`, `error`. | `info` |
| `GIT_SIGN_COMMITS` | 为提交、合并、重基、樱桃采摘和标签启用GPG/SSH签名。 | `false` |
| `GIT_AUTHOR_NAME` | Git作者姓名。别名： `GIT_USERNAME`, `GIT_USER`.返回到全局git配置。 | `(none)` |
| `GIT_AUTHOR_EMAIL` | Git作者电子邮件。别名： `GIT_EMAIL`, `GIT_USER_EMAIL`.返回到全局git配置。 | `(none)` |
| `GIT_BASE_DIR` | 将所有git操作限制到特定目录树的绝对路径。 | `(none)` |
| `GIT_WRAPUP_INSTRUCTIONS_PATH` | 带有工作流说明的自定义标记文件的路径。 | `(none)` |
| `MCP_AUTH_SECRET_KEY` | 需要 `jwt` auth。32+个字符的密钥。 | `(none)` |
| `OAUTH_ISSUER_URL` | 需要 `oauth` auth。OIDC提供者URL | `(none)` |


## 运行服务器


### 通过软件包管理器（无需安装）


SH```
1npx @cyanheads/git-mcp-server@latest

通过环境变量或MCP客户端配置进行配置。

本地开发

SH``` 1 2 3 4 5 6 7 8# 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员工


SH```
1
2
3npm run build:worker   # Build the worker bundle
npm run deploy:dev     # Run locally with Wrangler
npm run deploy:prod    # Deploy to Cloudflare

项目结构

目录	目的
`src/mcp-server/tools`	工具定义(`*.tool.ts`).Git功能就在这里。
`src/mcp-server/resources`	资源定义(`*.resource.ts`).Git上下文数据源。
`src/mcp-server/transports`	HTTP和STDIO传输实现，包括身份验证。
`src/storage`	`StorageService` 抽象和提供者实现。
`src/services`	Git服务提供商（基于CLI的Git操作）。
`src/container`	DI容器注册和令牌。
`src/utils`	日志记录、错误处理、性能、安全实用程序。
`src/config`	环境变量解析和验证（Zod）。
`tests/`	单元和集成测试、镜像 `src/` 结构。

响应格式

通过配置输出格式和详细程度 MCP_RESPONSE_FORMAT 和 MCP_RESPONSE_VERBOSITY.

JSON格式（默认，针对LLM消费进行了优化）：

JSON``` 1 2 3 4 5 6 7{ “success”: true, “branch”: “main”, “staged”: [“src/index.ts”, “README.md”], “unstaged”: [“package.json”], “untracked”: [] }


Markdown格式（人类可读）：

1 2 3 4 5 6# Git Status: main

Staged (2)

src/index.ts
README.md

Unstaged (1)

package.json


LLM始终通过以下方式接收完整的结构化数据 `responseFormatter` --完整的文件列表、元数据、时间戳——无论客户端显示什么。详细程度控制着包含多少细节： `minimal` （仅核心字段）， `standard` （平衡），或 `full` （一切）。


## 发展指南


看 AGENTS.md 架构、工具开发模式和贡献规则。


## 测试


测试使用 [邦氏试跑器](https://bun.sh/docs/cli/test) 具有Vitest兼容性。


SH```
1
2
3bun test              # Run all tests
bun test --coverage   # With coverage
bun run devcheck      # Lint, format, typecheck, audit

路线图

服务器使用基于提供者的架构进行git操作：

CLI提供程序 （当前）–通过本机git CLI全面覆盖28个工具。需要安装本地git。
同构git提供者 （计划中）——用于边缘部署的纯JS实现（Cloudflare Workers、Vercel edge、Deno Deploy）。用途同构git.
GitHub API提供程序 （也许）——通过GitHub REST/GraphQL API进行云原生操作，不需要本地仓库。

贡献

欢迎问题和拉取请求。提交前运行检查：

SH``` 1 2npm run devcheck npm test


## 许可证


Apache 2.0。看 许可证.



---



  Built with the [mcp-ts-template](https://github.com/cyanheads/mcp-ts-template)


  [Sponsor this project](https://github.com/sponsors/cyanheads) ·
    [Buy me a coffee](https://www.buymeacoffee.com/cyanheads)