Gitbucket MCP Server Rs

GitBucket MCP服务器

  

该服务器使AI助手（Claude Desktop、GitHub Copilot等）能够通过MCP协议与GitBucket存储库、标签、里程碑、问题和拉取请求进行交互。 这是一个非官方的社区项目，与GitBucket项目无关。

特性

• 库管理：列出、查看、创建、分叉存储库和列出分支
• 标签：列出、查看、创建、更新和删除存储库标签
• 里程碑：列出、查看、创建、更新和删除存储库里程碑
• 问题追踪：列出、查看、创建、更新问题；管理评论
• 拉取请求：列出、查看、创建、更新、合并PR；添加注释
• 用户信息：获取经过身份验证的用户并查找其他用户

需求

• 锈蚀1.70+
• 带有个人访问令牌的GitBucket实例

安装

GitHub发布

标记的版本发布预构建的档案：

• x86_64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-pc-windows-msvc

从GitHub Release下载与您的平台匹配的存档，提取并放置 gitbucket-mcp-server 在你的 PATH.

典型安装位置：

• Linux/macOS： ~/.local/bin/gitbucket-mcp-server 或已在上的另一个目录 PATH
• Windows：上的目录 PATH，例如 %USERPROFILE%\bin\gitbucket-mcp-server.exe

存档名称遵循以下模式：

gitbucket-mcp-server--.tar.gz
gitbucket-mcp-server--.zip

每个版本还包括 .sha256 校验和文件。

有关维护者发布步骤，请参阅 发布.md.

货物安装

从crates.io安装最新发布的版本：

cargo install gitbucket-mcp-server --locked

要直接从Git安装：

cargo install --git https://github.com/Masahiro-Obuchi/gitbucket-mcp-server-rs --locked

要安装标记的版本，请执行以下操作：

cargo install --git https://github.com/Masahiro-Obuchi/gitbucket-mcp-server-rs --tag v0.1.0 --locked

cargo install 将二进制文件放入 $CARGO_HOME/bin，通常是 ~/.cargo/bin 在Linux/macOS和 %CARGO_HOME%\bin 在Windows上（默认情况下 %USERPROFILE%\.cargo\bin).

来源

git clone https://github.com/Masahiro-Obuchi/gitbucket-mcp-server-rs.git
cd gitbucket-mcp-server-rs
cargo build --release

二进制文件将位于 target/release/gitbucket-mcp-server. 如果你想直接从shell或MCP客户端配置中使用它，请将其复制到 PATH例如 ~/.local/bin/.

配置

配置可以通过以下方式提供 TOML配置文件 和 环境变量.环境变量优先于配置文件。

配置文件

创建 ~/.config/gitbucket-mcp-server/config.toml:

url = "https://gitbucket.example.com"
token = "your-personal-access-token"

配置文件是通过以下方式创建的 0600 保护令牌的权限（仅限所有者读/写）。Web回退凭据是有意的 不 读取自 config.toml；set GITBUCKET_USERNAME 和 GITBUCKET_PASSWORD 仅通过环境变量。

配置目录可以用以下命令覆盖 GITBUCKET_MCP_CONFIG_DIR 环境变量。

环境变量

\*如果未在配置文件中设置，则为必填项。环境变量覆盖配置文件值。 GITBUCKET_USERNAME 和 GITBUCKET_PASSWORD 是可选的，但使用时必须一起设置。

GITBUCKET_USERNAME 和 GITBUCKET_PASSWORD 仅当此MCP服务器时使用 对于无法通过GitBucket进行的操作，可以回到GitBucket的web UI REST API。他们是 不 用于Git over HTTP操作，例如 git clone, git fetch，或 git push。如果出现以下情况，请单独配置Git凭据帮助程序 Git命令提示输入用户名或密码。

优先

1. 环境变量 （最高优先级）
2. TOML配置文件 (~/.config/gitbucket-mcp-server/config.toml)

创建个人访问令牌

1. 登录您的GitBucket实例
2. 首选 账户设置 → 个人访问令牌
3. 创建具有适当权限的新令牌

用法

独立

# Option 1: Using config file (recommended)
# First, create ~/.config/gitbucket-mcp-server/config.toml with url and token
gitbucket-mcp-server

# Option 2: Using environment variables
export GITBUCKET_URL="https://gitbucket.example.com"
export GITBUCKET_TOKEN="your-token"
export GITBUCKET_USERNAME="alice"         # optional, for web fallback operations
export GITBUCKET_PASSWORD="secret-pass"   # optional, env-only, not used by Git-over-HTTP commands
gitbucket-mcp-server

启动时，服务器会打印一条简短的准备就绪消息 stderr例如 gitbucket-mcp-server ready，而 stdout 仍保留用于MCP协议流量。

有关安装后烟雾检查，请参阅 验证.md.

克劳德桌面版

添加到您的Claude Desktop配置(~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gitbucket": {
      "command": "/path/to/gitbucket-mcp-server",
      "env": {
        "GITBUCKET_URL": "https://gitbucket.example.com",
        "GITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

VS代码/GitHub副本

gitbucket-mcp-server 必须已安装并可在您的 PATH. 使用下面的按钮将服务器配置添加到VS代码中：


对于手动设置，请将其添加到您的用户级VS Code MCP配置中。在VS码中， 使用 MCP：打开用户配置 并避免提交凭据或凭证 工作区的输入绑定 .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitbucket_url",
      "description": "GitBucket URL"
    },
    {
      "type": "promptString",
      "id": "gitbucket_token",
      "description": "GitBucket Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitbucket": {
      "command": "gitbucket-mcp-server",
      "env": {
        "GITBUCKET_URL": "${input:gitbucket_url}",
        "GITBUCKET_TOKEN": "${input:gitbucket_token}"
      }
    }
  }
}

如果你的GitBucket版本需要web回退来执行不需要的操作 通过REST API可用，将前面的示例替换为 遵循完整的用户级MCP配置，添加所需的VS代码 web回退凭据的输入变量和环境条目：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitbucket_url",
      "description": "GitBucket URL"
    },
    {
      "type": "promptString",
      "id": "gitbucket_token",
      "description": "GitBucket Personal Access Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "gitbucket_username",
      "description": "GitBucket username for web fallback"
    },
    {
      "type": "promptString",
      "id": "gitbucket_password",
      "description": "GitBucket password for web fallback",
      "password": true
    }
  ],
  "servers": {
    "gitbucket": {
      "command": "gitbucket-mcp-server",
      "env": {
        "GITBUCKET_URL": "${input:gitbucket_url}",
        "GITBUCKET_TOKEN": "${input:gitbucket_token}",
        "GITBUCKET_USERNAME": "${input:gitbucket_username}",
        "GITBUCKET_PASSWORD": "${input:gitbucket_password}"
      }
    }
  }
}

仅添加 GITBUCKET_USERNAME 和 GITBUCKET_PASSWORD 当你想要网络 回退已启用。它们必须放在一起；只留下一个空白或设置 其中之一会导致启动/配置错误。

Codex技能示例

此存储库包括Codex Skill示例，位于 skills/gitbucket-mcp/它为代理GitBucket提供了选择MCP工具、解释结构化列表结果、处理兼容性回退和确认破坏性操作的具体指导。

可用工具

仓库

问题

标签

里程碑

拉取请求

用户

结构化输出形状

MCP结构化结果始终是JSON对象。列表工具以稳定的字段名返回数组：

对于不公开REST标签更新端点的GitBucket版本， update_label 使用网络回退来更改名称/颜色。标准GitBucket不支持通过该回退进行标签描述更新；仅描述更新返回不受支持的错误，而即使请求中包含描述，名称/颜色更新也可以继续。

GitBucket的问题API没有暴露 closed_at 在某些版本上。当一个已关闭的问题没有 closed_at 但确实有 updated_at，此服务器填充 closed_at 和 updated_at 尽最大努力与GitHub兼容。

发展

构建

cargo build

测试

# Full test suite (used in CI)
cargo test

# Fast local checks without wiremock-based integration tests
cargo test --lib
cargo test --test mcp_server_test
cargo test --test e2e_test

棉绒

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings

CI

GitHub Actions对每个推送和拉取请求运行以下操作：

• cargo fmt --all --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test

分开的 E2E 工作流保留用于 workflow_dispatch 每晚跑步。它使用Docker启动一次性GitBucket，导出 GITBUCKET_E2E_*，运行 cargo test --test e2e_test -- --ignored --nocapture，之后总是把那堆东西撕下来。被忽略的套件涵盖了存储库创建路径、标签创建/读取/更新/删除生命周期、里程碑生命周期、问题流、问题web回退和拉取请求写入路径。

这 Release 工作流在上运行 v* 标记预构建的二进制档案并将其发布到GitHub Release。

建筑

src/
├── main.rs          # Entry point (stdio transport)
├── lib.rs           # Library root
├── server.rs        # MCP ServerHandler implementation
├── config.rs        # TOML file + environment variable configuration
├── error.rs         # Error types
├── api/             # GitBucket REST API client
│   ├── client.rs    # HTTP client with auth
│   ├── repository.rs
│   ├── milestone.rs
│   ├── issue.rs
│   ├── pull_request.rs
│   └── user.rs
├── models/          # API request/response types
│   ├── user.rs
│   ├── repository.rs
│   ├── milestone.rs
│   ├── issue.rs
│   ├── pull_request.rs
│   └── comment.rs
└── tools/           # MCP tool definitions
    ├── repository.rs
    ├── milestone.rs
    ├── issue.rs
    ├── pull_request.rs
    └── user.rs

测试注意事项

• tests/api_client_test.rs 用途 wiremock 以验证GitBucket API请求和响应。
• tests/mcp_server_test.rs 在内存传输上练习MCP工具表面。
• tests/e2e_test.rs 针对真实的GitBucket实例提供忽略的冒烟测试，包括使用分支发现创建存储库、标签生命周期覆盖率、里程碑生命周期覆盖、问题写入路径、问题web回退覆盖率和拉取请求创建/评论/合并流。
• MCP工具调用现在返回结构化成功有效载荷和结构化错误有效载荷(is_error=true)而不是 "Error: ..." 文本约定。
• src/tools/* 包括用于工具验证和成功路径行为的基于模拟的单元测试。

手动E2E测试

设置E2E环境变量，然后显式运行忽略的测试目标：

export GITBUCKET_E2E_URL="https://gitbucket.example.com/gitbucket"
export GITBUCKET_E2E_TOKEN="your-token"
export GITBUCKET_E2E_OWNER="owner"
export GITBUCKET_E2E_REPO="repo"
export GITBUCKET_E2E_GIT_USERNAME="git-http-username"
export GITBUCKET_E2E_GIT_PASSWORD="git-http-password"
export GITBUCKET_E2E_WEB_USERNAME="gitbucket-username"
export GITBUCKET_E2E_WEB_PASSWORD="gitbucket-password"
cargo test --test e2e_test -- --ignored --nocapture

可选变量：

• GITBUCKET_E2E_OWNER：默认为经过身份验证的用户 list_repositories
• GITBUCKET_E2E_REPO：里程碑、问题和针对现有存储库的拉取请求E2E所需
• GITBUCKET_E2E_GIT_USERNAME / GITBUCKET_E2E_GIT_PASSWORD：拉取请求写入路径E2E需要，因为测试通过HTTP创建和推送临时分支
• GITBUCKET_E2E_WEB_USERNAME / GITBUCKET_E2E_WEB_PASSWORD：用于web回退测试的可选显式凭据；如果省略，E2E将重用git凭据
• GITBUCKET_E2E_INSECURE_TLS=true：允许在E2E运行期间使用自签名或本地受信任的HTTPS证书
• 写路径E2E测试将创建的存储库、问题、注释、拉取请求和合并的分支留在原地；它们使用唯一的仓库名称、分支名称、标题和正文，以避免重新运行时发生冲突
• 里程碑E2E在同一测试中创建、更新和删除一个唯一的里程碑，这样重新运行就不会累积里程碑夹具

Docker E2E Bootstrap

您可以为E2E套件配置一个一次性本地GitBucket实例：

./scripts/e2e/bootstrap.sh
source ./.tmp/e2e/runtime.env
cargo test --test e2e_test -- --ignored --nocapture
./scripts/e2e/down.sh

GitHub Actions中也通过以下方式实现了相同的引导流自动化 .github/workflows/e2e.yml.使用常规 CI 快速反馈的工作流程和 E2E Docker支持的完整烟雾覆盖工作流程。

引导脚本使用Docker启动GitBucket，创建验证用户，发出个人访问令牌，创建初始化的目标存储库，并写入 ./.tmp/e2e/runtime.env 随着 GITBUCKET_E2E_* 预期变量 tests/e2e_test.rs，包括用于拉取请求E2E的git over HTTP凭据和存储库创建路径E2E所需的经过身份验证的上下文。

致谢

该项目的存在得益于 GitBucket 感谢您构建和维护使此MCP服务器值得创建的软件。

许可证

麻省理工学院