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; 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.

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches woodpecker-ci-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.