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.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

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

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Read tools are always registered. 🛡 marks the ones that need an instance administrator; 👤 marks the ones that ask a person before acting, through MCP elicitation, falling back to a two-call confirm_token where the client cannot show a dialog.

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose. Seventeen tools that answered with a sentence — "Pipeline 12 was cancelled." — now answer with the fields as well, and the sentence stays where a reader wants it. get_step_logs keeps its rendered header-plus-log in the text and states the exit code, the line count and the output as fields.

The tools that report pushed content carry untrusted: true and source: "woodpecker" as fields; branch names, commit messages, pipeline titles and above all build logs — the raw stdout of arbitrary containers — are written by whoever can push. The list follows the call sites: a tool is marked exactly when it already routed its answer through the untrusted wrapper.

Woodpecker's objects are described as open objects with the top-level keys this server builds. The upstream Go models change what they serialize between releases, and the SDK validates each result against its schema before it goes out — a strict shape would turn a field a release adds into a tool that fails outright. 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-four operations ask a person. Every delete_*, plus move_repository, chown_repository, the whole-instance repair_repository, create_forge, update_forge, pause_queue and approve_pipeline — and six more only in the direction that escalates: update_user granting admin, create_user creating one, update_repository granting a trusted_* flag or lowering the fork gate (require_approval down, visibility to public), update_secret overwriting a value or widening who may read it, update_registry replacing a password, and set_log_level silencing the server.

  Where the client supports MCP elicitation that is a real dialog the model cannot answer on its behalf. Where it does not, the first call returns a short-lived token bound to those exact arguments and only a second call carrying it acts — which proves the call was made twice with the same arguments and nothing more, and the text says so. Either way an approval for one repository is not one for another, and one for a tool is not one for another. ELICITATION=false takes the fallback deliberately; it never removes the guard. See Asking a person.

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

Documentation

The full guide, tool reference and security notes live at woodpecker-ci-mcp.ni-c.de (source in docs/).

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.

Contributing

Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.

License

MIT © Willi Thiel