MCP Git

🚀 mcp-server-git：一个用于Git的MCP服务器

mcp-server-git是一个用于与Git仓库进行交互和自动化操作的Model Context Protocol（MCP）服务器。它借助大语言模型，提供了读取、搜索和操作Git仓库的工具。

请注意，mcp-server-git目前处于早期开发阶段。随着服务器的持续开发和改进，其功能和可用工具可能会发生变化和扩展。

✨ 主要特性

• 提供一系列用于操作Git仓库的工具，涵盖状态查看、差异比较、提交记录、分支管理等常见操作。
• 支持多种安装方式，包括使用uv和pip。
• 可通过环境变量进行配置，支持从不同位置的.env文件加载配置。
• 能与Claude Desktop、VS Code、Zed等工具集成使用。
• 提供调试和开发相关的支持，方便开发者进行测试和改进。

📦 安装指南

使用uv（推荐）

当使用 uv 时，无需进行特定安装。我们将使用 uvx 直接运行 mcp-server-git。

使用PIP

你也可以通过pip安装 mcp-server-git：

pip install mcp-server-git

安装完成后，你可以使用以下命令将其作为脚本运行：

python -m mcp_server_git

💻 使用示例

工具列表及使用说明

1. git_status

• 功能：显示工作树的状态
• 输入：
  • repo_path (字符串)：Git仓库的路径
• 返回：以文本输出形式呈现的工作目录当前状态

2. git_diff_unstaged

• 功能：显示工作目录中尚未暂存的更改
• 输入：
  • repo_path (字符串)：Git仓库的路径
• 返回：未暂存更改的差异输出

3. git_diff_staged

• 功能：显示已暂存待提交的更改
• 输入：
  • repo_path (字符串)：Git仓库的路径
• 返回：已暂存更改的差异输出

4. git_diff

• 功能：显示分支或提交之间的差异
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • target (字符串)：用于比较的目标分支或提交
• 返回：当前状态与目标之间的差异输出

5. git_commit

• 功能：将更改记录到仓库
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • message (字符串)：提交信息
• 返回：包含新提交哈希的确认信息

6. git_add

• 功能：将文件内容添加到暂存区
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • files (字符串数组)：要暂存的文件路径数组
• 返回：已暂存文件的确认信息

7. git_reset

• 功能：取消所有已暂存的更改
• 输入：
  • repo_path (字符串)：Git仓库的路径
• 返回：重置操作的确认信息

8. git_log

• 功能：显示提交日志
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • max_count (数字，可选)：要显示的最大提交数（默认值：10）
• 返回：包含哈希、作者、日期和信息的提交条目数组

9. git_create_branch

• 功能：创建一个新分支
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • branch_name (字符串)：新分支的名称
  • start_point (字符串，可选)：新分支的起始点
• 返回：分支创建的确认信息

10. git_checkout

• 功能：切换分支
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • branch_name (字符串)：要切换到的分支名称
• 返回：分支切换的确认信息

11. git_show

• 功能：显示提交的内容
• 输入：
  • repo_path (字符串)：Git仓库的路径
  • revision (字符串)：要显示的版本（提交哈希、分支名称、标签）
• 返回：指定提交的内容

12. git_init

• 功能：初始化一个Git仓库
• 输入：
  • repo_path (字符串)：要初始化Git仓库的目录路径
• 返回：仓库初始化的确认信息

📚 详细文档

配置

环境变量

服务器支持从 .env 文件加载环境变量，优先级顺序如下：

1. 项目特定的.env文件 - 当前工作目录中的 .env 文件
2. 仓库特定的.env文件 - 仓库目录中的 .env 文件（使用 --repository 参数时）
3. ClaudeCode工作目录的.env文件 - ClaudeCode工作区根目录中的 .env 文件（自动检测）
4. 系统环境变量 - 标准环境变量

示例.env文件

在你的项目目录或ClaudeCode工作区中创建一个 .env 文件：

# 用于GitHub集成功能的GitHub API令牌
# 从以下地址获取令牌：https://github.com/settings/tokens
GITHUB_TOKEN=your_github_token_here

# 可选：自定义GitHub API基本URL（用于GitHub Enterprise）
# GITHUB_API_BASE_URL=https://api.github.com

# 可选：调试日志级别
# LOG_LEVEL=INFO

注意：服务器启动时会自动加载 .env 文件。服务器会从当前工作目录和仓库路径（如果通过 --repository 参数提供）向上遍历，智能检测ClaudeCode工作区目录。如果未找到 .env 文件，服务器将使用系统环境变量。

对于ClaudeCode用户：如果你的 .env 文件位于ClaudeCode工作区根目录（例如 /home/memento/ClaudeCode/.env），从该工作区内的任何子目录运行MCP服务器时，它将自动检测并加载该文件。

与Claude Desktop集成使用

将以下内容添加到你的 claude_desktop_config.json 中：

"mcpServers": {
  "git": {
    "command": "uvx",
    "args": ["mcp-server-git", "--repository", "path/to/git/repo"]
  }
}

"mcpServers": {
  "git": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "--mount", "type=bind,src=/Users/username,dst=/Users/username", "mcp/git"]
  }
}

"mcpServers": {
  "git": {
    "command": "python",
    "args": ["-m", "mcp_server_git", "--repository", "path/to/git/repo"]
  }
}

与VS Code集成使用

快速安装

使用以下一键安装按钮之一：

手动安装

将以下JSON块添加到VS Code的用户设置（JSON）文件中。你可以通过按下 Ctrl + Shift + P 并输入 Preferences: Open Settings (JSON) 来完成此操作。

可选地，你可以将其添加到工作区中名为 .vscode/mcp.json 的文件中。这样可以与他人共享配置。

注意，.vscode/mcp.json 文件中不需要 mcp 键。

{
  "mcp": {
    "servers": {
      "git": {
        "command": "uvx",
        "args": ["mcp-server-git"]
      }
    }
  }
}

对于Docker安装：

{
  "mcp": {
    "servers": {
      "git": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "--mount", "type=bind,src=${workspaceFolder},dst=/workspace",
          "mcp/git"
        ]
      }
    }
  }
}

与 Zed 集成使用

将以下内容添加到你的Zed settings.json 中：

"context_servers": [
  {
    "mcp-server-git": {
      "command": {
        "path": "uvx",
        "args": ["mcp-server-git"]
      }
    }
  }
],

"context_servers": {
  "mcp-server-git": {
    "command": {
      "path": "python",
      "args": ["-m", "mcp_server_git"]
    }
  }
},

🔧 技术细节

调试

你可以使用MCP检查器来调试服务器。对于uvx安装：

npx @modelcontextprotocol/inspector uvx mcp-server-git

或者，如果你将软件包安装在特定目录中或正在对其进行开发：

cd path/to/servers/src/git
npx @modelcontextprotocol/inspector uv run mcp-server-git

运行 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log 将显示服务器的日志，可能有助于你调试任何问题。

开发

如果你正在进行本地开发，有两种方法可以测试你的更改：

1. 运行MCP检查器来测试你的更改。有关运行说明，请参阅 调试。
2. 使用Claude桌面应用程序进行测试。将以下内容添加到你的 claude_desktop_config.json 中：

Docker

{
  "mcpServers": {
    "git": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/git"
      ]
    }
  }
}

UVX

{
  "mcpServers": {
    "git": {
      "command": "uv",
      "args": [
        "--directory",
        "/<path to mcp-servers>/mcp-servers/src/git",
        "run",
        "mcp-server-git"
      ]
    }
  }
}

构建

Docker构建：

cd src/git
docker build -t mcp/git .

📄 许可证

此MCP服务器采用MIT许可证。这意味着你可以自由使用、修改和分发该软件，但需遵守MIT许可证的条款和条件。有关更多详细信息，请参阅项目仓库中的 LICENSE 文件。