内容
# woodpecker-mcp
[](https://github.com/KalvadTech/woodpecker-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
Woodpecker CI 的 MCP 服务器。无状态 — 每个请求都携带自己的身份验证令牌。
## 功能
- 查询仓库、流水线、日志、定时任务、机密、代理、组织、用户和系统信息
- 触发、重启、取消、批准和拒绝流水线
- 管理定时任务和仓库机密
- 每个请求的身份验证（无状态，可水平扩展）
## 配置
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `WOODPECKER_SERVER` | 是 | — | 您的 Woodpecker 服务器 URL（例如 `https://ci.example.com`） |
| `MCP_ALLOWED_HOSTS` | 否 | `localhost` | DNS 重绑定保护允许列表（`*` 禁用） |
身份验证通过 `Authorization: Bearer <token>` HTTP 头进行每个请求的身份验证。
## 快速入门
```bash
# 安装依赖
make install
# 设置您的 Woodpecker 服务器 URL（与 Woodpecker CLI 相同的环境变量）
export WOODPECKER_SERVER=https://ci.example.com
# 启动服务器
make run
```
服务器监听 `http://127.0.0.1:8080`。
## 连接 MCP 客户端
### Claude Code
项目根目录中的 `.mcp.json`：
```json
{
"mcpServers": {
"woodpecker": {
"type": "http",
"url": "http://127.0.0.1:8080/mcp",
"headers": {
"Authorization": "Bearer {env:WOODPECKER_TOKEN}"
}
}
}
}
```
### opencode
将远程 MCP 服务器添加到您的 `opencode.json`：
```json
{
"mcp": {
"woodpecker": {
"type": "remote",
"url": "http://localhost:8080/mcp",
"enabled": true,
"oauth": false,
"headers": {
"Authorization": "Bearer {env:WOODPECKER_TOKEN}"
}
}
}
}
```
在启动 opencode 之前，在您的 shell 中设置 `WOODPECKER_TOKEN`（与 Woodpecker CLI 相同的环境变量）。如果 `{env:...}` 插值在您的版本中不起作用，请使用 `{file:~/.config/opencode/.secrets/woodpecker-token}` 代替，或硬编码令牌。
### 其他 MCP 客户端
将您的 MCP 客户端指向 Streamable HTTP 端点 (`http://localhost:8080/mcp`)，并在每个请求中将您的 Woodpecker 个人访问令牌作为 `Authorization: Bearer <token>` 发送。
## 可用工具
| 类别 | 工具 |
|---|---|
| **仓库** | `search_repositories`, `get_repository`, `list_branches`, `list_pull_requests`, `repair_repository` |
| **流水线** | `list_pipelines`, `get_pipeline`, `trigger_pipeline`, `restart_pipeline`, `cancel_pipeline`, `approve_pipeline`, `get_pipeline_config` |
| **日志** | `get_step_logs`, `list_pipeline_steps` |
| **定时任务** | `list_cron_jobs`, `create_cron_job`, `delete_cron_job`, `trigger_cron_job` |
| **机密** | `list_repo_secrets`, `create_repo_secret`, `delete_repo_secret` |
| **代理** | `list_agents`, `get_agent`, `list_agent_tasks` |
| **组织** | `list_organizations`, `get_organization`, `get_org_permissions` |
| **用户** | `list_users`, `get_current_user`, `get_user_feed` |
| **系统** | `get_health`, `get_version`, `get_queue_info` |
| **源** | `list_forges` |
| **网址** | `open_woodpecker_url` |
**总计：37 个工具**
## 部署
```sh
docker run --rm -p 8080:8080 \
-e WOODPECKER_SERVER=https://ci.example.com \
ghcr.io/kalvadtech/woodpecker-mcp:latest
```
镜像是多阶段 Alpine，运行为非 root 用户，并暴露 8080。
## 开发
```bash
make install # 安装依赖
make run # 启动服务器（需要 WOODPECKER_SERVER）
make test # 运行测试
make lint # 使用 ruff 进行 lint
make format # 使用 ruff 进行格式化
make typecheck # 使用 ty 进行类型检查
make check # 运行所有检查（lint + 格式化 + 类型检查 + 测试）
make clean # 删除虚拟环境
```
## 贡献
欢迎提交拉取请求。请：
- 遵循 [Conventional Commits](https://www.conventionalcommits.org/)，
- 保持更改简洁和范围明确（每个提交一个逻辑更改），
- 为任何行为更改添加或更新测试，
- 在打开 PR 之前运行 `pytest`、`ruff` 和 `ty` clean。
## 许可证
[MIT](LICENSE) (c) 2026 Kalvad.
