使用说明

GitBucket MCP服务器

A. 模型上下文协议（MCP）服务器用于 GitBucket，用Rust写的。

该服务器使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-<version>-<target>.tar.gz
gitbucket-mcp-server-<version>-<target>.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_URL`	✅*	GitBucket实例URL	`https://gitbucket.example.com`
`GITBUCKET_TOKEN`	✅*	个人访问令牌	`abc123...`
`GITBUCKET_USERNAME`	❌	用于web回退操作的GitBucket用户名	`alice`
`GITBUCKET_PASSWORD`	❌	用于web回退操作的GitBucket密码	`secret-pass`
`GITBUCKET_MCP_CONFIG_DIR`	❌	覆盖配置目录	`/custom/path`

*如果未在配置文件中设置，则为必填项。环境变量覆盖配置文件值。 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命令提示输入用户名或密码。

优先

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

创建个人访问令牌

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

用法

独立

# 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工具、解释结构化列表结果、处理兼容性回退和确认破坏性操作的具体指导。

可用工具

仓库

工具	说明
`list_repositories`	列出用户或组织的存储库
`get_repository`	获取存储库详细信息
`create_repository`	创建新存储库
`fork_repository`	分叉存储库
`list_branches`	列出存储库的分支

问题

工具	说明
`list_issues`	列出问题（可按州筛选）
`get_issue`	获取问题详细信息
`create_issue`	创建新问题
`update_issue`	更新问题（状态、标题、正文）
`list_issue_comments`	列出对某个问题的评论
`add_issue_comment`	向问题添加评论

里程碑

工具	说明
`list_milestones`	列出存储库的里程碑
`get_milestone`	获取里程碑详细信息
`create_milestone`	创建新的里程碑
`update_milestone`	更新里程碑字段和状态
`delete_milestone`	删除里程碑

拉取请求

工具	说明
`list_pull_requests`	列出拉取请求（可按状态筛选）
`get_pull_request`	获取PR详细信息
`create_pull_request`	创建新的pull请求
`update_pull_request`	更新PR状态、标题、正文或基本分支
`merge_pull_request`	合并拉取请求
`add_pull_request_comment`	在pull请求中添加注释

用户

工具	说明
`get_authenticated_user`	获取经过身份验证的用户信息
`get_user`	按用户名获取用户

结构化输出形状

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

工具	结果字段
`list_repositories`	`repositories`
`list_branches`	`branches`
`list_issues`	`issues`
`list_issue_comments`	`comments`
`list_labels`	`labels`
`list_milestones`	`milestones`
`list_pull_requests`	`pull_requests`

对于不公开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服务器值得创建的软件。

许可证

麻省理工学院

工具	说明
`list_labels`	列出存储库的标签
`get_label`	获取标签详细信息
`create_label`	创建新标签
`update_label`	更新标签名称、颜色或描述；REST不兼容的GitBucket实例在名称/颜色上回退
`delete_label`	删除标签

使用说明

GitBucket MCP服务器

特性

需求

安装

GitHub发布

货物安装

来源

配置

配置文件

环境变量

优先

创建个人访问令牌

用法

独立

克劳德桌面版

VS代码/GitHub副本

Codex技能示例

可用工具

仓库

问题

标签

里程碑

拉取请求

用户

结构化输出形状

发展

构建

测试

棉绒

CI

建筑

测试注意事项

手动E2E测试

Docker E2E Bootstrap

致谢

许可证

相关 MCP

小红书MCP服务

Figma MCP集成工具

Git仓库管理MCP服务器

MCP 协议测试服务器

Flomo笔记服务

GitLab项目管理服务器