Git MCP Server

---

工具

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 上下文和指令，用于由大模型驱动的变更日志分析
分支与合并	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、createTag。

入门

运行时

同时支持 Bun 和 Node.js。运行时会自动检测。

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

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中（例如，cline_mcp_settings.json）。根据你的设置更新环境变量，尤其是 Git 身份字段。

{
  "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 用户：将 "command": "npx" 替换为 "command": "bunx"。

对于 Streamable HTTP，请设置 MCP_TRANSPORT_TYPE=http 和 MCP_HTTP_PORT=3015。

功能

基于 mcp-ts-template 构建。

功能	详情
声明式工具	在单个独立文件中定义功能。框架负责注册、验证和执行。
错误处理	统一的 McpError 系统，提供一致且结构化的错误响应。
身份验证	支持 none、jwt 和 oauth 模式。
可插拔存储	可切换后端（in-memory、filesystem、Supabase、Cloudflare KV/R2），无需更改业务逻辑。
可观测性	结构化日志记录（Pino）以及可选的自动插桩 OpenTelemetry，用于追踪和指标。
依赖注入	使用 tsyringe 构建，实现解耦且易于测试的架构。
跨运行时	自动检测 Bun 或 Node.js，并使用相应的进程生成方法。
提供商架构	可插拔的 git 提供商系统。当前：CLI。计划中：用于边缘部署的 isomorphic-git。
工作目录管理	为多仓库工作流提供特定于会话的目录上下文。
可配置的 git 身份	通过环境变量覆盖作者／提交者信息，并回退至全局 git 配置。
提交签名	对提交、合并、变基、摘取和标签进行 GPG/SSH 签名（默认启用）。失败时静默回退为未签名，并在响应中包含 signed／signingWarning 字段。
安全性	破坏性操作（git clean、git reset --hard）需要显式确认标志。

安全

• 验证并清理所有文件路径，以防止目录遍历。
• 可选的 GIT_BASE_DIR 可将操作限制在特定目录树中，以实现多租户沙盒隔离。
• Git 命令通过进程生成使用经过验证的参数，不进行 Shell 插值。
• 支持用于经过身份验证的部署的 JWT 和 OAuth。
• 可选地通过 DI 管理的 RateLimiter 服务进行速率限制。
• 所有操作都会连同请求上下文一起记录，以供审计。

配置

所有配置都会在启动时于 src/config/index.ts 中验证。主要环境变量：

Variable	Description	Default
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	auto
MCP_RESPONSE_FORMAT	响应格式：json（针对大模型优化）、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	启用 OpenTelemetry。	false
MCP_LOG_LEVEL	最低日志级别：debug、info、warn、error。	info
GIT_SIGN_COMMITS	对提交、合并、变基、挑拣提交和标签进行 GPG/SSH 签名。失败时回退为不签名（参见响应中的 signed/signingWarning）。	true
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	包含工作流说明的自定义 markdown 文件路径。	(none)
MCP_AUTH_SECRET_KEY	jwt 身份验证必需。长度至少为 32 个字符的密钥。	(none)
OAUTH_ISSUER_URL	oauth 身份验证必需。OIDC 提供商 URL。	(none)

运行服务

通过包管理器使用（无需安装）

npx @cyanheads/git-mcp-server@latest

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

本地开发

# 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

项目结构

目录	用途
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 格式（默认，针对大模型消费进行了优化）：

{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}

Markdown 格式（便于人类阅读）：

# Git Status: main

## Staged (2)
- src/index.ts
- README.md

## Unstaged (1)
- package.json

无论客户端显示什么内容，大模型都会通过 responseFormatter 收到完整的结构化数据，包括完整的文件列表、元数据和时间戳。详细程度控制包含的信息量：minimal（仅核心字段）、standard（平衡）或 full（全部内容）。

开发指南

请参阅 AGENTS.md，了解架构、工具开发模式和贡献规则。

测试

测试使用 Bun 的测试运行器，并兼容 Vitest。

bun test              # Run all tests
bun test --coverage   # With coverage
bun run devcheck      # Lint, format, typecheck, audit

路线图

该服务采用基于提供程序的架构执行 Git 操作：

• CLI 提供程序（当前）——通过原生 Git CLI 完整支持 28 个工具。需要本地安装 Git。
• Isomorphic git 提供程序（计划中）——用于边缘部署（Cloudflare Workers、Vercel Edge、Deno Deploy）的纯 JS 实现。使用 isomorphic-git。
• GitHub API 提供程序（可能）——通过 GitHub REST/GraphQL API 执行云原生操作，无需本地仓库。

贡献

欢迎提交 Issue 和 Pull Request。提交前请运行检查：

npm run devcheck
npm test

许可证

Apache 2.0。请参阅 LICENSE。

---