# @cyanheads/git-mcp-server 中文文档

规范地址：https://npmcn.com/package/%40cyanheads/git-mcp-server/

版本：2\.15\.3
npm 元数据更新时间：2026-08-24T21:56:00.402Z
中文译文更新时间：2026-11-11T06:06:46.358Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyanheads/git-mcp-server
原文对照：https://npmcn.com/package/%40cyanheads/git-mcp-server/?lang=original
项目主页：https://github.com/cyanheads/git-mcp-server#readme
源码仓库：https://github.com/cyanheads/git-mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.7 MB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- 首次发布：2025-04-02T17:19:53.814Z
- 最新版本发布：2026-08-24T21:56:00.237Z
- 近 30 天下载量：14002（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 33 个）

## 中文简介

一个安全可扩展的Git MCP服务器,使AI代理能够通过STDIO和Streamable HTTP执行全面的Git版本控制操作.

## 安装

```sh
npm install @cyanheads/git-mcp-server
```

也可以使用：`pnpm add @cyanheads/git-mcp-server`、`yarn add @cyanheads/git-mcp-server`、`bun add @cyanheads/git-mcp-server`

## README

# @cyanheads/git-mcp-服务器

**一个用于AI代理的Git MCP服务器. STIO & 流式 HTTP.**

28 工具 资源 1 提示

[![Version](https://img.shields.io/badge/Version-2.15.3-blue.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/git-mcp-server/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-%5E1.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)](https://npmcn.com/package/%40cyanheads/git-mcp-server/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-%5E6.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/)

* * *

## 工具

28个基特业务,分为7个类别:

| 类别 | 工具 | 说明 |
| :-- | :-- | :-- |
| **仓库管理** | `git_init`, (中文(简体) ), `git_clone`, (中文(简体) ), `git_status`, (中文(简体) ), `git_clean` | 初始化重置、 从远程复制、 检查状态、 清理未跟踪文件 |
| **显示提交( C)** | `git_add`, (中文(简体) ), `git_commit`, (中文(简体) ), `git_diff` | 阶段变化、 创建承诺、 比较变化 |
| **历史和检查** | `git_log`, (中文(简体) ), `git_show`, (中文(简体) ), `git_blame`, (中文(简体) ), `git_reflog` | 视图传输历史, 检查对象, 跟踪作者身份, 视图查看日志 |
| **分析** | `git_changelog_analyze` | 为 LLM 驱动的更改日志分析收集 git 上下文和指令 |
| **分支合并( M)** | `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一起工作 运行时间是自动检测的.

| 运行时间 | 命令 | 最小版本 |
| :-- | :-- | :-- |
| **节点.js** | `npx @cyanheads/git-mcp-server@latest` | 页:1 |
| **阿宝** | `bunx @cyanheads/git-mcp-server@latest` | 1.2.0 |

### MCP 客户端配置

添加以下内容到您的 MCP 客户端配置( 例如 ), `cline_mcp_settings.json`) (中文(简体) ). 更新环境变量以匹配您的设置—— 尤其是 git 身份字段 .

```json
{
  "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` 模式. |
| 可插件存储 | 交换后端( E)`in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `Supabase`, (中文(简体) ), `Cloudflare KV/R2`),不改变业务逻辑. |
| 观察性 | 有结构的伐木(Pino)和可选的可自动装置的可追踪和可测量的OpenTeleometry. |
| 依赖性注射 | 与 `tsyringe` 对于脱钩的,可测试的建筑. |
| 交叉运行时间 | 自动检测出Bun或Node.js,并使用适当的过程产卵法. |
| 供应商结构 | 可插接的git供应商系统. 目前:CLI. 计划:边缘部署的同位素-基特. |
| 工作目录管理 | 多重播工作流程的会话特定目录上下文. |
| 可配置的 git 身份 | 通过环境变量来覆盖作者/commiters信息,并返回到全局git配置. |
| 提交签名 | GPG/SSH 签名(默认情况下),用于承诺、合并、再基、樱桃签和标记。 在失败时悄悄倒向未签名 `signed`编号 :`signingWarning` 字段中的响应. |
| 安全问题 | 破坏行动(`git clean`, (中文(简体) ), `git reset --hard`需要明确确认旗帜. |

## 警卫

-   所有文件路径都经过验证和消毒,以防止目录的转录.
-   可选 `GIT_BASE_DIR` 将操作限制在用于多租户沙箱的特定目录树上.
-   Git指令通过过程产卵使用经过验证的参数——无外壳插值.
-   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` | 启用 OpenTeleometry . | `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`。返回到全球图形配置. | `(none)` |
| `GIT_AUTHOR_EMAIL` | Git 作者邮件. 别名 : `GIT_EMAIL`, (中文(简体) ), `GIT_USER_EMAIL`。返回到全球图形配置. | `(none)` |
| `GIT_BASE_DIR` | 将所有 git 操作限制到特定目录树的绝对路径 . | `(none)` |
| `GIT_WRAPUP_INSTRUCTIONS_PATH` | 带有工作流程指令的自定义标记下文件路径 . | `(none)` |
| `MCP_AUTH_SECRET_KEY` | 所需经费 `jwt` auth. 32+ 字符密钥. | `(none)` |
| `OAUTH_ISSUER_URL` | 所需经费 `oauth` 授权。 OIDC 供应商 URL. | `(none)` |

## 运行服务器

### Via 软件包管理器( 无安装)

```sh
npx @cyanheads/git-mcp-server@latest
```

通过环境变量或您的 MCP 客户端配置配置 .

### 地方发展

```sh
# 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
```

### 云花岗工人

```sh
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`) (中文(简体) ). 基特能力就在这里. |
| `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
{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}
```

标记下的格式( 人可读) :

```
# Git Status: main

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

## Unstaged (1)
- package.json
```

LLM 总是通过 `responseFormatter` ——完整文件列表,元数据,时间戳——无论客户端显示什么. Verbosity控制包含多少细节: `minimal` (只有核心领域), `standard` (平衡),或 `full` (诸事.

## 发展指南

见 [`AGENTS.md`](https://npmcn.com/package/%40cyanheads/git-mcp-server/AGENTS.md) 用于建筑、工具开发模式和贡献规则.

## 测试

测试使用情况 [Bun的测试跑道](https://bun.sh/docs/cli/test) 与 Vitest 兼容.

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

## 路线图

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

-   **CLI 供应商** (目前)——通过土生土长的git CLI实现全28个工具覆盖. 需要安装本地基特.
-   **异态提供商** (计划)——实施边境部署的纯JS(Cloudflare Workers,Vercel Edge,Deno部署). 用途 [同位素 - git](https://isomorphic-git.org/)。 。 。 .
-   **GitHub API 供应商** (可能)——通过GitHub REST/GraphQL API进行云-内生操作,不需要本地回放.

## 捐款

欢迎提出问题和拉动请求。 提交前运行检查 :

```sh
npm run devcheck
npm test
```

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://npmcn.com/package/%40cyanheads/git-mcp-server/LICENSE)。 。 。 .

* * *

与该建筑 [mcp-t-t-template (缩写)](https://github.com/cyanheads/mcp-ts-template)

[赞助这个项目](https://github.com/sponsors/cyanheads) • 妇女 [给我买杯咖啡](https://www.buymeacoffee.com/cyanheads)

## 常见问题

### @cyanheads/git-mcp-server 是什么？

一个安全可扩展的Git MCP服务器,使AI代理能够通过STDIO和Streamable HTTP执行全面的Git版本控制操作\.

### 如何安装 @cyanheads/git-mcp-server？

在项目目录运行 npm install @cyanheads/git-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 git-mcp-server，可以用 npx git-mcp-server 直接运行。

### @cyanheads/git-mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyanheads/git-mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cyanheads/git-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyanheads/git-mcp-server 可以商用吗？

@cyanheads/git-mcp-server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyanheads/git-mcp-server 的下载量有多少？

根据 npm 官方下载统计，@cyanheads/git-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 14,002 次，日均约 467 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyanheads/git-mcp-server 还在维护吗？

最新版本 2\.15\.3 发布于 2026/08/25（2 个月前）；至今共发布 80 个版本，其中过去 12 个月发布了 33 个；首次发布于 2025/04/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。