# Woodpecker CI [Health: Active] **Category:** πŸ”’ Security **Repository:** https://github.com/ni-c/woodpecker-ci-mcp **GitHub Stars:** 0 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/woodpecker-ci ## Description Read Woodpecker CI repositories, pipelines and logs, and drive builds, secrets and crons ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "woodpecker-ci": { "command": "npx", "args": ["-y","@ni-c/woodpecker-ci-mcp"] } } ``` ## Documentation & README # woodpecker-ci-mcp [![CI](https://img.shields.io/github/actions/workflow/status/ni-c/woodpecker-ci-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/woodpecker-ci-mcp/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/woodpecker-ci-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/woodpecker-ci-mcp) Socket supply-chain report [![Glama score](https://glama.ai/mcp/servers/ni-c/woodpecker-ci-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/woodpecker-ci-mcp)
[![npm version](https://img.shields.io/npm/v/%40ni-c%2Fwoodpecker-ci-mcp)](https://www.npmjs.com/package/@ni-c/woodpecker-ci-mcp) [![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fwoodpecker--ci--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/woodpecker-ci-mcp/pkgs/container/woodpecker-ci-mcp) [![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
[![docs](https://img.shields.io/badge/docs-woodpecker--ci--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://woodpecker-ci-mcp.ni-c.de) [![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c) A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Woodpecker CI](https://woodpecker-ci.org), 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](#choosing-which-tools-load). An MCP client talks to woodpecker-ci-mcp over stdio; the server calls the Woodpecker CI API over HTTPS. ![Finding a failed pipeline, reading the failing step's log, and restarting it](https://woodpecker-ci-mcp.ni-c.de/demo.gif) ## 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 | 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) | | `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. > **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](https://woodpecker-ci-mcp.ni-c.de/reference/tools). ```sh 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](https://mcp-hub.ni-c.de) is the other answer β€” its `/hub` endpoint replaces every server's tools with six meta-tools. ## Installation ### Claude Code ```sh claude mcp add woodpecker-ci -- npx -y @ni-c/woodpecker-ci-mcp ``` ### Claude Desktop ```json { "mcpServers": { "woodpecker-ci": { "command": "npx", "args": ["-y", "@ni-c/woodpecker-ci-mcp"], "env": { "WOODPECKER_URL": "https://woodpecker.example.com", "WOODPECKER_TOKEN": "…" } } } } ``` ### Codex ```toml [mcp_servers.woodpecker-ci] command = "npx" args = ["-y", "@ni-c/woodpecker-ci-mcp"] env = { WOODPECKER_URL = "https://woodpecker.example.com", WOODPECKER_TOKEN = "…" } ``` ### Docker ```sh 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 `: 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](https://mcp-hub.ni-c.de): 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: ```json { "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](https://woodpecker-ci-mcp.ni-c.de/guide/clients#through-mcp-hub). ## 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](https://woodpecker-ci-mcp.ni-c.de/reference/tools) has the parameters. ### Repositories | Tool | Description | | ---------------------------- | ------------------------------------------------------------------ | | `list_repositories` | Repositories, optionally including ones not yet activated | | `get_repository` | One repository with all its Woodpecker settings | | `lookup_repository` | Turns `owner/name` into the id every other tool takes | | `get_repository_permissions` | What this account may do here β€” answers "why that 403" | | `list_repository_branches` | Branches, as Woodpecker sees them in the forge | | `list_pull_requests` | Open pull requests and their index | | `activate_repository` | Turns Woodpecker on for a forge repository | | `update_repository` πŸ‘€ | Config file, timeout, visibility, approval mode; πŸ‘€ to grant trust | | `repair_repository` πŸ‘€ | Re-installs the webhook; πŸ‘€ only for the whole-instance variant | | `move_repository` πŸ‘€ | Follows a repository that moved in the forge | | `chown_repository` πŸ‘€ | Takes ownership, so the token Woodpecker uses is yours | | `delete_repository` πŸ‘€ | Removes it from Woodpecker with all its history | ### Pipelines and logs | Tool | Description | | ----------------------- | ------------------------------------------------------------ | | `list_pipelines` | Pipelines with branch, event, status and time filters | | `get_pipeline` | One pipeline with its workflows, steps and step ids | | `get_pipeline_config` | The YAML this run was built from | | `get_pipeline_metadata` | The `CI_*` environment a step saw, and the previous run | | `list_queued_pipelines` | What is waiting, across all repositories | | `get_step_logs` | A step's output as text, tail first, with its exit code | | `trigger_pipeline` | Starts a pipeline on a branch | | `restart_pipeline` | Runs an existing one again, at the same commit | | `cancel_pipeline` | Stops a pending or running pipeline | | `approve_pipeline` πŸ‘€ | Releases a blocked one β€” it runs fork code with your secrets | | `decline_pipeline` | Refuses a blocked one | | `delete_pipeline` πŸ‘€ | Deletes a pipeline and its logs | | `delete_step_logs` πŸ‘€ | Deletes one step's output β€” for when a step printed a secret | | `delete_pipeline_logs` | πŸ‘€ The same for every step of a pipeline | ### Secrets, registries and crons `scope` selects the level: `repository`, `organization` or `global`. | Tool | Description | | -------------------- | ------------------------------------------------------------- | | `list_secrets` | Secrets at one level. Values are never returned by Woodpecker | | `get_secret` | One secret's events, images and note | | `create_secret` | Creates one. At least one event is required | | `update_secret` πŸ‘€ | Rotates the value (πŸ‘€), or replaces the event and image lists | | `delete_secret` πŸ‘€ | Deletes one; pipelines using it run without it | | `list_registries` | Container registry credentials at one level | | `get_registry` | One entry. The password is stripped by Woodpecker | | `create_registry` | Stores credentials for pulling private images | | `update_registry` | Changes username or password | | `delete_registry` πŸ‘€ | Removes them | | `list_crons` | Scheduled runs and when each fires next | | `get_cron` | One cron job | | `create_cron` | Schedules a run β€” five-field cron or `@daily` | | `update_cron` | Changes it, including `enabled` to pause without deleting | | `run_cron` | Runs it now, without touching the schedule | | `delete_cron` πŸ‘€ | Removes the schedule | ### Accounts, organizations and instance administration | Tool | Description | | ------------------------------ | ------------------------------------------------------------ | | `get_current_user` | Which account the token belongs to, and whether it is admin | | `get_pipeline_feed` | The latest pipeline of every visible repository, in one call | | `list_organizations` πŸ›‘ | Organizations known to the instance | | `get_organization` | One organization | | `lookup_organization` | Turns a name into the id org-level tools need | | `get_organization_permissions` | Member and admin flags for this account | | `delete_organization` πŸ›‘πŸ‘€ | Removes it with its org-level secrets, registries and agents | | `list_users` πŸ›‘ | Accounts that have ever logged in | | `get_user` πŸ›‘ | One account β€” `forge_id` is required | | `create_user` πŸ›‘πŸ‘€ | Pre-creates a record; πŸ‘€ only when it grants admin | | `update_user` πŸ›‘πŸ‘€ | Changes email; πŸ‘€ to grant admin | | `delete_user` πŸ›‘πŸ‘€ | Removes an account β€” transfer its repositories first | | `list_agents` πŸ›‘ | Build agents, with tokens redacted | | `get_agent` πŸ›‘ | One agent, token redacted | | `list_agent_tasks` πŸ›‘ | What an agent is running right now | | `create_agent` πŸ›‘ | Registers one and returns its token β€” a credential | | `update_agent` πŸ›‘ | Rename, relabel, or drain with `no_schedule` | | `delete_agent` πŸ›‘πŸ‘€ | Removes it and invalidates its token | | `list_forges` πŸ›‘ | Forges this instance authenticates against | | `get_forge` πŸ›‘ | One forge; the OAuth secret is never returned | | `create_forge` πŸ›‘πŸ‘€ | Adds a forge β€” a way to sign in, so it asks first | | `update_forge` πŸ›‘πŸ‘€ | Changes one β€” a wrong value locks everyone out | | `delete_forge` πŸ›‘πŸ‘€ | Removes one | | `get_server_info` | Version and health. Works without a token | | `get_queue_info` πŸ›‘ | The server-side queue and agent statistics | | `get_log_level` πŸ›‘ | Current server log level | | `pause_queue` πŸ›‘πŸ‘€ | Stops scheduling for the whole instance | | `resume_queue` πŸ›‘ | Starts it again | | `set_log_level` πŸ›‘πŸ‘€ | Changes it; πŸ‘€ to silence the server | ## 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](https://woodpecker-ci-mcp.ni-c.de/guide/approval). - **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](https://woodpecker-ci-mcp.ni-c.de)** (source in [`docs/`](https://github.com/ni-c/woodpecker-ci-mcp/blob/HEAD/docs/)). ## Development ```sh 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](https://github.com/ni-c/woodpecker-ci-mcp/blob/HEAD/CONTRIBUTING.md). For vulnerabilities please use [private reporting](https://github.com/ni-c/woodpecker-ci-mcp/security/advisories/new) rather than a public issue; the policy is in [SECURITY.md](https://github.com/ni-c/woodpecker-ci-mcp/blob/HEAD/SECURITY.md). ## License [MIT](https://github.com/ni-c/woodpecker-ci-mcp/blob/HEAD/LICENSE) Β© Willi Thiel