ni-c/woodpecker-ci-mcp

A Model Context Protocol (MCP) server for
Woodpecker CI, the lightweight container-native CI
engine — it runs your pipelines, and this reads and drives them.
Lets MCP clients like Claude Code, Claude Desktop or Codex see which pipelines
failed, read the build log of the step that broke, and act on it — restart it,
cancel a runaway, approve a blocked one, rotate a secret, fix a cron — with the
irreversible operations put to a person first and the write tools
switchable off entirely.
71 tools is the ceiling, not the floor: WOODPECKER_ALLOW_TOOLS=essential
registers a curated eight instead, and a model picks the right tool far more
reliably from eight than from 71 — see
choosing which tools load.
What makes it different
**It covers the whole API, not the read half.** Repositories, pipelines, logs,
secrets, registries, crons, organizations, users, agents, forges, the queue and
the log level — 71 tools against Woodpecker 3.18.0. The point of an MCP server
for a CI system is doing something about what it tells you.
**Logs arrive as text.** Woodpecker returns a step's output as an array of
base64-encoded chunks with line numbers. get_step_logs decodes them, puts them
back in order, reports the step's exit code, and returns the **end** of the log
by default — a failing step explains itself in its last lines, and the first 4000
lines of npm ci answer nothing.
**Agent tokens do not reach the model.** GET /agents returns every agent's
token in clear text, and that token is enough to attach a machine to the server
and receive pipeline workloads with their secrets. Listing agents through this
server redacts it. create_agent still returns one — that is the only way to get
it — and says what it is.
**It knows where this API is sharp.** /version and /healthz sit outside the
/api prefix that the Swagger document claims for them, so GET /api/version
returns the web UI with HTTP 200 rather than a 404 (3.19 adds them under /api
and 4.0 drops the root routes, so get_server_info falls back to the prefix); a repository that exists in
the forge is a 404 here until it is activated; perPage above 50 is clamped
without a word; a cron schedule is five fields, not six; and a secret with no
event list is refused, because the defaults people expect live in the web UI, not
in the API.
Requirements
- Node.js ≥ 22
- A **Woodpecker** personal access token — your user settings, "CLI and API".
There are no scopes: the token carries the full authority of your account.
Configuration
| Variable | Required | Description |
| ------------------------- | -------- | ---------------------------------------------------------------------------------- |
| WOODPECKER_URL | yes | Root URL of the server, e.g. https://woodpecker.example.com |
| WOODPECKER_TOKEN | yes | Personal access token from your user settings |
| WOODPECKER_READ_ONLY | no | true registers only the 34 read tools |
| WOODPECKER_ALLOW_TOOLS | no | Comma-separated tool names, list_* prefixes, or essential for a curated preset |
| WOODPECKER_DENY_TOOLS | no | Same syntax; removed from whatever WOODPECKER_ALLOW_TOOLS left |
| WOODPECKER_INSECURE_TLS | no | true accepts self-signed certificates (scoped to this connection) |
| WOODPECKER_API_PREFIX | no | Path of the API below the root, default /api. Crow CI 5 and later: /api/v1 |
| ELICITATION | no | false replaces the approval dialog with the two-call token. **Not prefixed** |
WOODPECKER_URL is the server root, not the API root:
https://woodpecker.example.com, not https://woodpecker.example.com/api. Both
are accepted — the suffix is trimmed — because the Swagger page spells every
example the long way.
**Crow CI**, a Woodpecker fork, serves its API under /api/v1 since 5.0: set
WOODPECKER_API_PREFIX=/api/v1. That makes the API reachable, not identical —
this server speaks the Woodpecker 3 API, and Crow ignores a few of its fields.
See Crow CI.
> **Use https://.** Over plain http the token travels unencrypted; the server
> prints a warning unless the host is local. For self-signed certificates prefer a
> proper internal CA over WOODPECKER_INSECURE_TLS.
Without configuration the server still starts and lists its tools (so registries
and inspectors can introspect it); every call then fails with setup instructions