Woodpecker Ci MCP Server

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 behind a confirmation token 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; 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

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.

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 instead of reaching the API. get_server_info works without a token, which makes it the first thing to call when nothing else does: if it answers, WOODPECKER_URL is right and the problem is the token.

Admin-only tools. Woodpecker inherits repository and organization permissions from the forge, and reserves users, agents, forges, the queue and the log level for instance administrators. Those tools are registered for everyone and answer 403 for accounts that may not use them; get_current_user reports which kind of account the token belongs to, and WOODPECKER_DENY_TOOLS is the tidy way to stop offering them at all.

Choosing which tools load

WOODPECKER_ALLOW_TOOLS and WOODPECKER_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset — list_repositories, get_repository, list_pipelines, get_pipeline, get_step_logs, trigger_pipeline, restart_pipeline and cancel_pipeline — marked as such in the tool reference.

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

With 71 tools this is not a nicety. Every visible tool costs context on every request, and a server that offers delete_forge next to get_step_logs is a server nobody should point at their production CI without narrowing it first.

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under WOODPECKER_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

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

If your Woodpecker is only resolvable through your host's split DNS, add --dns <resolver>: a container does not inherit the host's resolver configuration, and the public answer for an internal name is usually an address that does not respond.

Tools

Read tools are always registered. 🛡 marks the ones that need an instance administrator; 👤 marks the ones that ask for a confirmation token before acting. The tool reference has the parameters.

Repositories

Pipelines and logs

Secrets, registries and crons

scope selects the level: repository, organization or global.

Accounts, organizations and instance administration

Not exposed, on purpose

• POST/DELETE /user/token. They return and rotate the personal access token of the account this server authenticates as. A tool that hands the model its own credential is not a feature, and one that invalidates the server's own configuration mid-session is worse. The web UI does both, in front of a person.
• POST /hook. The forge webhook endpoint. Calling it means forging a push event, which is a way to run a pipeline while making it look like someone committed something. trigger_pipeline is the honest version.
• /debug/pprof/*. Nine endpoints of Go profiling data. A heap dump is not something to put in a model's context.
• /stream/events and /stream/logs. Server-sent event streams do not fit a request/response tool. Poll get_pipeline instead.
• Badge endpoints. They return SVG and XML for embedding, not information.

Safety

• Twenty operations are two-step. Every delete_*, plus move_repository, the whole-instance repair_repository, update_forge, pause_queue and approve_pipeline — and four more only in the direction that escalates: update_user granting admin, update_repository granting a trusted_* flag, update_secret overwriting a value, and set_log_level silencing the server. The first call returns a short-lived confirmation token bound to those exact arguments; only a second call carrying it acts. A token for one repository is not a token for another, and a token for one tool is not a token for another.
• Agent tokens are redacted on read — see above. create_agent is the exception, by necessity.
• Secret values and registry passwords are never returned, and not because this server hides them: Woodpecker strips them from every response, including the one immediately after creating them. Store the value somewhere else too.
• Build logs, commit messages and pipeline metadata are marked as untrusted data, because they are written by whoever can push to the repository. Confirmation prompts never quote anything that came from the API.
• Error bodies are truncated, HTML error pages are dropped, and every response has a byte ceiling enforced while it streams. Log output has a much smaller budget of its own, and says when it was cut.
• WOODPECKER_READ_ONLY=true does not register the write tools at all, and WOODPECKER_DENY_TOOLS cuts finer along the same line — a filtered tool is never built, not refused at call time.
• The token is deleted from process.env once it has been read, is never sent to a redirect target, and is never echoed into an error message.

Development

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

Releasing

1. Add the CHANGELOG entry and bump package.json.
2. npm run lint && npm run build && npm run test:coverage
3. Commit, then push a signed tag: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

The release workflow publishes to npm (Trusted Publishing, with provenance), creates the GitHub release from the CHANGELOG section and updates the MCP Registry entry.