Woodpecker CI

woodpecker-ci-mcp

一个面向 Woodpecker CI 的模型上下文协议（MCP）服务。Woodpecker CI 是一款轻量级、容器原生的 CI 引擎——它运行你的流水线，而此服务负责读取和操作流水线。

它让 Claude Code、Claude Desktop 或 Codex 等 MCP 客户端能够查看哪些流水线失败，读取出错步骤的构建日志，并采取相应操作——重新启动、取消失控的流水线、批准被阻止的流水线、轮换密钥、修复 cron——不可逆操作会先交由人工处理，而且可以完全关闭写入工具。

71 个工具只是上限，不是最低配置：设置 WOODPECKER_ALLOW_TOOLS=essential 即可改为注册精心挑选的 8 个工具。模型从 8 个工具中选择正确工具的可靠性远高于从 71 个中选择——请参阅选择要加载的工具。

与众不同之处

它涵盖整个 API，而不只是读取部分。 仓库、流水线、日志、密钥、镜像仓库、定时任务、组织、用户、Agent、代码托管平台、队列和日志级别——针对 Woodpecker 3.18.0 提供 71 个工具。CI 系统的 MCP 服务就该能对它告知的信息采取行动。

日志以文本形式返回。 Woodpecker 会将步骤输出作为包含行号的 base64 编码数据块数组返回。get_step_logs 会对其解码、按顺序重新排列、报告步骤的退出代码，并默认返回日志的末尾——失败步骤会在最后几行说明原因，而 npm ci 的前 4000 行毫无帮助。

Agent 令牌不会传给模型。 GET /agents 会以明文返回每个 Agent 的令牌，而该令牌足以将一台机器接入服务并接收包含密钥的流水线工作负载。通过此服务列出 Agent 时，令牌会被隐藏。create_agent 仍会返回令牌——这是获取令牌的唯一方式——并明确说明它是什么。

它了解这个 API 中容易出问题的地方。 /version 和 /healthz 位于 Swagger 文档所称的 /api 前缀之外，因此 GET /api/version 会返回网页 UI，HTTP 状态码为 200，而不是 404（3.19 将它们添加到了 /api 下，4.0 则移除了根路由，因此 get_server_info 会回退到带前缀的路径）；在代码托管平台中存在的仓库，在此处尚未激活前会返回 404；超过 50 的 perPage 值会被静默限制；cron 调度表达式有 5 个字段，而不是 6 个；没有事件列表的密钥会被拒绝，因为人们期待的默认值存在于网页 UI 中，而不是 API 里。

要求

• Node.js ≥ 22
• 一个 Woodpecker 个人访问令牌——位于用户设置中的“CLI and API”页面。 令牌没有作用域：它拥有你账户的全部权限。

配置

变量	必填	描述
WOODPECKER_URL	是	服务的根 URL，例如 https://woodpecker.example.com
WOODPECKER_TOKEN	是	用户设置中的个人访问令牌
WOODPECKER_READ_ONLY	否	true 仅注册 34 个只读工具
WOODPECKER_ALLOW_TOOLS	否	逗号分隔的工具名称、list_* 前缀，或用于精选预设的 essential
WOODPECKER_DENY_TOOLS	否	语法相同；从 WOODPECKER_ALLOW_TOOLS 保留的工具中移除指定项
WOODPECKER_INSECURE_TLS	否	true 接受自签名证书（仅限此连接）
WOODPECKER_API_PREFIX	否	根路径下的 API 路径，默认为 /api。Crow CI 5 及更高版本：/api/v1
ELICITATION	否	false 将审批对话框替换为两次调用令牌。不带前缀

WOODPECKER_URL 是服务根 URL，而不是 API 根 URL： https://woodpecker.example.com，而不是 https://woodpecker.example.com/api。两种写法 都可用——后缀会被移除——因为 Swagger 页面中的示例都采用较长的写法。

Crow CI 是 Woodpecker 的一个分支，自 5.0 起通过 /api/v1 提供 API：设置 WOODPECKER_API_PREFIX=/api/v1。这样 API 就可以访问了，但并不完全兼容—— 此服务使用 Woodpecker 3 API，而 Crow 会忽略其中几个字段。 参见 Crow CI。

请使用 https://。 使用普通 http 时，令牌会以未加密的形式传输；除非主机是本地地址，否则服务 会打印警告。对于自签名证书，建议使用正规的内部 CA，而不是 WOODPECKER_INSECURE_TLS。

即使未配置，服务仍会启动并列出其工具（以便注册表和检查器进行检视）；但之后的每次调用都会失败并显示设置说明， 而不会访问 API。get_server_info 无需令牌即可使用；当其他操作都无法正常工作时，应首先调用它：如果它能 返回结果，说明 WOODPECKER_URL 正确，问题出在令牌上。

仅限管理员使用的工具。 Woodpecker 从代码托管平台继承仓库和组织权限，并将用户、 Agent、代码托管平台、队列和日志级别的管理权限保留给实例管理员。这些工具会向所有人注册，但无权使用的账户调用时会收到 403；get_current_user 会报告令牌所属的账户类型，而 WOODPECKER_DENY_TOOLS 是彻底停止 提供这些工具的简便方式。

选择加载哪些工具

WOODPECKER_ALLOW_TOOLS 和 WOODPECKER_DENY_TOOLS 接受以逗号分隔的工具名称；末尾的 * 可匹配整个工具系列。essential 是一组精选预设，包含 list_repositories、get_repository、list_pipelines、get_pipeline、get_step_logs、trigger_pipeline、restart_pipeline 和 cancel_pipeline，并在工具参考中标记。

WOODPECKER_ALLOW_TOOLS=essential
WOODPECKER_ALLOW_TOOLS=list_*,get_pipeline,get_step_logs
WOODPECKER_DENY_TOOLS=delete_*,pause_queue,create_user,update_user

有 71 个工具时，这并非小题大做。每个可见工具都会在每次请求中占用上下文；如果一个服务同时提供 delete_forge 和 get_step_logs，那么在缩小范围之前，没人应该让它连接到生产 CI。

如果某个条目与任何工具都不匹配，启动就会中止并指出该条目，因此拼写错误不会悄悄隐藏工具——工具缺失时，没人会想到去追查环境变量。经过筛选的工具不会被注册，因此它既不会出现在 tools/list 中，也不会被 tools/call 识别，这与 WOODPECKER_READ_ONLY 下的写入工具完全一样。

如果你同时运行多个此类服务，mcp-hub 也是一种解决方案——它的 /hub 端点会用六个元工具取代每个服务的所有工具。

安装

Claude Code

claude mcp add woodpecker-ci -- npx -y @ni-c/woodpecker-ci-mcp

Claude Desktop

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "npx",
      "args": ["-y", "@ni-c/woodpecker-ci-mcp"],
      "env": {
        "WOODPECKER_URL": "https://woodpecker.example.com",
        "WOODPECKER_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.woodpecker-ci]
command = "npx"
args = ["-y", "@ni-c/woodpecker-ci-mcp"]
env = { WOODPECKER_URL = "https://woodpecker.example.com", WOODPECKER_TOKEN = "…" }

Docker

docker run --rm -i \
  -e WOODPECKER_URL=https://woodpecker.example.com \
  -e WOODPECKER_TOKEN=… \
  ghcr.io/ni-c/woodpecker-ci-mcp

如果你的 Woodpecker 只能通过主机的分离式 DNS 解析，请添加 --dns <resolver>：容器不会继承主机的解析器配置，而内部名称的公共解析结果通常是一个无法响应的地址。

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、Claude 网页版、Cursor、LibreChat——可通过 mcp-hub 连接 woodpecker-ci-mcp：一个容器即可通过 Streamable HTTP 提供多个 stdio MCP 服务，并在单个密码后提供 OAuth 2.1 登录，以及为无法使用 OAuth 的客户端提供长期令牌。它的 /hub 端点会将所有服务置于六个元工具之后，因此一个连接器就能访问所有服务，而无需在模型上下文中放入 N×工具架构；它还支持两个协议修订版本——此服务提出的问题会经由它传递给另一端的用户。

它的 /config/mcp.json 使用 Claude Code 的格式，因此可以直接使用你已有的配置项：

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "npx",
      "args": ["-y", "@ni-c/woodpecker-ci-mcp"],
      "env": {
        "WOODPECKER_URL": "https://woodpecker.example.com",
        "WOODPECKER_TOKEN": "…"
      }
    }
  }
}

其中的 allowTools 和 denyTools 是 hub 自己针对每个服务的筛选设置，与 env 中的 *_ALLOW_TOOLS 并不相同——两者的区别及其容易引发的错误，详见客户端指南。

工具

读取工具始终会注册。🛡 标记需要实例管理员权限的工具；👤 标记执行前会通过 MCP 征询请求用户确认的工具。客户端无法显示对话框时，则会回退到两次调用的 confirm_token。

每个工具都会声明一个 outputSchema，并在文本块之外通过 structuredContent 返回结果，因此客户端无需解析散文即可使用结果。原先会用一句话回答的 17 个工具——“Pipeline 12 已取消。”——现在也会返回相应字段，而这句话仍会保留在读者希望看到的位置。get_step_logs 会在文本中保留渲染后的标题和日志，并将退出代码、行数和输出作为字段返回。

报告已推送内容的工具会带有 untrusted: true 和 source: "woodpecker" 字段；分支名称、提交消息、Pipeline 标题，尤其是构建日志——任意容器的原始标准输出——都由有权推送的人编写。此列表与调用位置保持一致：只有当工具的回答已经通过不可信内容包装器处理时，才会标记该工具。

Woodpecker 的对象被描述为开放对象，并列出此服务构建的顶层键。上游 Go 模型在不同版本之间序列化的内容会有变化，而且 SDK 会在返回结果之前根据其架构进行验证——严格限定结构会导致某个版本新增的字段使工具直接失败。 参数请参阅工具参考。

仓库

工具	描述
list_repositories	仓库，可选择包含尚未激活的仓库
get_repository	单个仓库及其所有 Woodpecker 设置
lookup_repository	将 owner/name 转换为其他工具所需的 ID
get_repository_permissions	此账号在此处可以执行的操作——回答“为什么会返回 403”
list_repository_branches	Woodpecker 在代码托管平台中看到的分支
list_pull_requests	未关闭的拉取请求及其索引
activate_repository	为代码托管平台上的仓库启用 Woodpecker
update_repository 👤	配置文件、超时、可见性、审批模式；👤 用于授予信任
repair_repository 👤	重新安装 Webhook；👤 仅适用于整个实例的变体
move_repository 👤	跟踪在代码托管平台上迁移的仓库
chown_repository 👤	接管所有权，这样 Woodpecker 使用的令牌就属于你
delete_repository 👤	从 Woodpecker 中删除仓库及其全部历史记录

流水线和日志

工具	描述
list_pipelines	按分支、事件、状态和时间筛选流水线
get_pipeline	单条流水线及其工作流、步骤和步骤 ID
get_pipeline_config	此次运行所依据的 YAML
get_pipeline_metadata	步骤读取到的 CI_* 环境变量及上一次运行
list_queued_pipelines	所有代码库中正在等待的任务
get_step_logs	步骤输出的文本，优先显示末尾内容，并附带退出代码
trigger_pipeline	在某个分支上启动流水线
restart_pipeline	在相同提交上重新运行现有流水线
cancel_pipeline	停止待处理或正在运行的流水线
approve_pipeline 👤	放行被阻止的流水线 — 它会使用你的机密运行分叉代码
decline_pipeline	拒绝被阻止的流水线
delete_pipeline 👤	删除流水线及其日志
delete_step_logs 👤	删除某个步骤的输出 — 适用于步骤打印了机密的情况
delete_pipeline_logs	👤 删除流水线所有步骤的日志

机密、镜像仓库和定时任务

scope 用于选择级别：repository、organization 或 global。

工具	描述
list_secrets	列出某个级别的机密。Woodpecker 永远不会返回机密值
get_secret	查看某个机密的事件、镜像和备注
create_secret	创建一个机密。至少需要一个事件
update_secret 👤	轮换机密值（👤），或替换事件和镜像列表
delete_secret 👤	删除一个机密；使用它的流水线将不再使用该机密
list_registries	列出某个级别的容器镜像仓库凭据
get_registry	查看某个条目。Woodpecker 会移除密码
create_registry	保存用于拉取私有镜像的凭据
update_registry	更改用户名或密码
delete_registry 👤	移除该凭据
list_crons	列出定时运行及下一次触发时间
get_cron	查看某个定时任务
create_cron	安排运行 — 使用五字段 cron 表达式或 @daily
update_cron	修改定时任务，包括将 enabled 设为暂停，而不删除任务
run_cron	立即运行，不影响定时安排
delete_cron 👤	移除定时安排

账户、组织和实例管理

工具	描述
get_current_user	令牌所属的账户，以及该账户是否为管理员
get_pipeline_feed	一次调用即可获取所有可见仓库的最新流水线
list_organizations 🛡	实例已知的组织
get_organization	获取一个组织
lookup_organization	将名称转换为组织级工具所需的 ID
get_organization_permissions	此账户的成员和管理员标记
delete_organization 🛡👤	删除组织及其组织级密钥、注册表和 Agent
list_users 🛡	曾登录过的账户
get_user 🛡	获取一个账户——必须提供 forge_id
create_user 🛡👤	预先创建一条记录；仅在授予管理员权限时需要 👤
update_user 🛡👤	更改邮箱；授予管理员权限时需要 👤
delete_user 🛡👤	删除账户——请先转移其仓库
list_agents 🛡	构建 Agent，令牌已隐藏
get_agent 🛡	获取一个 Agent，令牌已隐藏
list_agent_tasks 🛡	查看 Agent 当前正在运行的任务
create_agent 🛡	注册一个 Agent 并返回其令牌——这是一项凭据
update_agent 🛡	重命名、重新标记，或使用 no_schedule 将其排空
delete_agent 🛡👤	删除 Agent 并使其令牌失效
list_forges 🛡	此实例进行身份验证所用的平台
get_forge 🛡	获取一个平台；不会返回 OAuth 密钥
create_forge 🛡👤	添加一个平台——它是登录方式，因此会先征求确认
update_forge 🛡👤	更改一个平台——错误的值会导致所有人都无法登录
delete_forge 🛡👤	删除一个平台
get_server_info	版本和运行状况。无需令牌即可使用
get_queue_info 🛡	服务端队列和 Agent 统计信息
get_log_level 🛡	当前服务端日志级别
pause_queue 🛡👤	停止为整个实例调度任务
resume_queue 🛡	重新启动调度
set_log_level 🛡👤	更改日志级别；要静默服务端需要 👤

有意不暴露的接口

• POST/DELETE /user/token。 这些接口会返回并轮换此服务用于身份验证的账户的个人访问令牌。让工具把自身凭据交给模型算不上功能；在会话中途使服务自身配置失效则更糟。网页 UI 会由用户操作这两项功能。
• POST /hook。 Forge 的 Webhook 端点。调用它就意味着伪造推送事件，这样就能运行流水线，同时让人以为有人提交了内容。trigger_pipeline 才是坦诚的做法。
• /debug/pprof/*。 九个 Go 性能分析数据端点。堆转储不该放进模型的上下文。
• /stream/events 和 /stream/logs。 服务端发送的事件流不适合请求/响应式工具。改用 get_pipeline 轮询。
• 徽章端点。 它们返回用于嵌入的 SVG 和 XML，而非信息。

安全

• 二十四项操作需要用户确认。 所有 delete_* 操作，以及 move_repository、chown_repository、针对整个实例的 repair_repository、create_forge、update_forge、pause_queue 和 approve_pipeline；另外还有六项仅在权限升级方向需要确认：update_user 授予 admin 权限、create_user 创建具有该权限的用户、update_repository 授予 trusted_* 标记或降低分支门槛（将 require_approval 调低、将 visibility 设为 public）、update_secret 覆盖值或扩大可读取者范围、update_registry 替换密码，以及 set_log_level 静默服务。

  如果客户端支持 MCP elicitation，就会弹出一个模型无法代替用户作答的真实对话框。如果不支持，首次调用会返回一个短时令牌，该令牌绑定这些确切参数；只有第二次调用携带该令牌才会执行操作。这只能证明使用相同参数调用了两次，不代表其他任何内容，提示文本也会明确说明这一点。无论哪种方式，一个仓库的批准都不能用于另一个仓库，一个工具的批准也不能用于另一个工具。ELICITATION=false 会有意采用回退机制，但绝不会移除防护。请参阅向用户请求确认。

• 读取时会对 Agent 令牌进行脱敏——见上文。create_agent 是出于必要而设的例外。

• 绝不返回密钥值和注册表密码，这并非此服务隐藏了它们：Woodpecker 会从所有响应中剔除这些内容，包括创建它们后的紧接着的响应。请将值另行存储。

• 构建日志、提交消息和流水线元数据都会标记为不可信数据，因为任何有权推送到仓库的人都能写入这些内容。确认提示绝不引用任何来自 API 的内容。

• 错误响应体会被截断，HTML 错误页面会被丢弃，并且每个响应都会在流式传输时强制执行字节上限。日志输出还有更小的独立预算，并会说明何时被截断。

• WOODPECKER_READ_ONLY=true 会彻底不注册写入工具；WOODPECKER_DENY_TOOLS 则会沿用相同原则进行更细粒度的筛选——被筛除的工具根本不会构建，而不是在调用时被拒绝。

• 令牌读取后会从 process.env 中删除，不会发送给重定向目标，也绝不会回显到错误消息中。

文档

完整指南、工具参考和安全说明请见 woodpecker-ci-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install
npm run lint && npm run build && npm run test:coverage

发布

1. 添加 CHANGELOG 条目并更新 package.json 中的版本。
2. npm run lint && npm run build && npm run test:coverage
3. 提交，然后推送已签名的标签：git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

发布工作流会将软件包发布到 npm（使用 Trusted Publishing，并附带来源证明），根据 CHANGELOG 部分创建 GitHub 发布，并更新 MCP Registry 条目。

贡献

欢迎提交问题、参与讨论和发起拉取请求 — 请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私下报告渠道，不要公开提交问题；相关政策请参阅 SECURITY.md。

许可证

MIT © Willi Thiel