woodpecker-mcp

MCP connector for a self-hosted Woodpecker CI v3.20.1 REST API. It speaks official /api JSON over stdio and over stateless Streamable HTTP on localhost.

Woodpecker is Apache-2.0 software (LICENSE in the v3.20.1 source tree). This connector is MIT. It does not copy Woodpecker source. It is not affiliated with woodpecker-ci/woodpecker.

spec/api-inventory.json is a compact extraction of every gin /api route registered in v3.20.1 server/router/api.go. It records the release version, Apache-2.0, file sha256s, and routeTreeSha256. scripts/gen-operations.mjs maps that inventory onto tool actions or exclusions and writes src/operations.ts and woodpecker.routes.json. A route that is neither mapped nor excluded fails generation. Do not edit src/operations.ts by hand. Default generation and npm run ci read only the committed inventory.

WOODPECKER_URL and WOODPECKER_TOKEN (or WOODPECKER_TOKEN_FILE) are required. There is no default origin. The connector does not start Woodpecker. Each request sends Authorization: Bearer. The token is never placed in the URL.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.

{
  "mcpServers": {
    "woodpecker": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "WOODPECKER_URL": "http://127.0.0.1:8800",
        "WOODPECKER_TOKEN": "...",
        "WOODPECKER_ALLOW_WRITES": "false"
      }
    }
  }
}

The token is a Woodpecker personal access token from User settings → CLI and API. The connector never prints it.

HTTP mode has no authentication of its own. Keep it on localhost. Do not put secrets in a Docker image.

docker build -t woodpecker-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -e WOODPECKER_URL=http://127.0.0.1:8800 \
  -e WOODPECKER_TOKEN=... \
  woodpecker-mcp

Regenerate the registry from the committed inventory.

npm run gen:operations
node scripts/gen-operations.mjs --check

Refresh the inventory from an official v3.20.1 tree. This is the only command that reads route source. Keep that tree outside this MIT connector (for example /workspace/tools/woodpecker/upstream/source-root).

node scripts/gen-operations.mjs --source-root /path/to/woodpecker --write-inventory
node scripts/gen-operations.mjs --source-root /path/to/woodpecker --check

WOODPECKER_SOURCE_ROOT is accepted by a write run. --check ignores that variable unless you also pass --source-root.

scripts/live-check.mjs talks to a real server over stdio. Set WOODPECKER_URL. Set WOODPECKER_TOKEN or WOODPECKER_TOKEN_FILE to a chmod 600 file outside this repo. The script unsets DATABASE_URL. It prints pass or fail lines only, and it redacts the token and live secret values. It does not run inside npm run ci. A missing token is a failure.

Isolated local runtime scripts live under /workspace/tools/woodpecker (start.sh, stop.sh). They keep sqlite and secrets under /tmp/woodpecker-mcp.

Related MCP server: drone-mcp-server

Config

Invalid values are reported by field name and issue code. The rejected value is not included.

Calls go to /api/... paths from the operations registry. Accept is application/json. JSON writes send Content-Type: application/json. Redirects are refused so the token is not forwarded. There are no automatic retries, including HTTP 429. The token is never placed in the URL, query, or User-Agent.

Safety

Reads run without a write flag. A write is sent only when confirm is the boolean true and WOODPECKER_ALLOW_WRITES=true. That gate covers every mutation in the registry: activate, update, repair, chown, delete repo, trigger, cancel, restart, approve, decline, delete pipeline, delete logs, cron create/update/delete/run, and secret create/update/delete at repo, org, and global scope. Omit confirm, or pass boolean false, and the tool returns a dry-run preview of method, path, query, and body. It sends nothing. blocked is false on that preview, whether or not writes are enabled. confirm: true with writes disabled returns the same preview with blocked true and the reason WOODPECKER_ALLOW_WRITES is not true. The write was not sent. The string "true" is rejected.

Omitted fields are dropped. enabled: false and an empty branch: "" on cron update are sent when you set them. A field that is not valid for the selected action is rejected before any request is sent. Unknown fields are rejected.

HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 400 and 422 are invalid input. HTTP 404 is not found. HTTP 409 is conflict. HTTP 429 includes Retry-After when the header is present. Other failures are server, network, or timeout. Response bodies are capped at 1,000,000 bytes.

Every non-empty string or number under a sensitive key on that request is a secret, at any nesting depth and inside arrays or objects below that key, including 1-character values and values longer than 64 characters. Sensitive keys include token, password, authorization, secret values under the JSON key value, apiKey/apikey, session, cookie, credential, passphrase, privateKey, and similar names. The path parameter secret is the secret's name and is not treated as a credential. The configured token (minimum 8 characters) and any URL userinfo found in the request are included too. Secrets are collected once per request and are not kept for the next call.

Sensitive-key values become [redacted] in objects. Substring masking of free text (raw, percent-encoded any-case hex, and JSON-escaped forms) runs only for secrets of length 8 or more. If the request carries a shorter credential, upstream free-text error bodies and log detail are replaced with upstream detail omitted because this request carried a short credential. Object keys and this connector's preview envelope (method, path, summary, executed, and the other write-gate fields) are not rewritten. That rule covers MCP success results, MCP error text, write previews, HTTP and network errors, and every logger line.

Secret value is sent on the HTTP create/update body and is stripped from previews, results, errors, and logs.

Tools

Six tools. Each takes action plus the fields for that action. Fields for a different action are rejected.

health calls GET /api/healthz. v3.20.1 answers HTTP 204; this connector returns { ok: true, status: 204 }. The connector's own Streamable HTTP GET /health is separate and returns the plain text ok. lookup needs repo_full_name as owner/name. activate needs forge_remote_id (the forge's repository id). create pipeline needs branch. Secret create needs name, value, and events. Step logs decode Woodpecker's base64 data into text.

53 of 123 expanded v3.20.1 /api routes are mapped. 70 are excluded. The registry has 53 actions and 26 writes. See woodpecker.routes.json for every mapping and exclusion reason.

Coverage and exclusions

In scope: current user, version/health, queue info, repository list/lookup/get/activate/update/repair/chown/delete, branches, pull requests, permissions, workflows, pipeline list/get/trigger/cancel/restart/approve/decline/delete/config/metadata, step logs read and delete, cron CRUD and run, repo/org/global secret CRUD.

Excluded with a stored reason, grouped:

• Admin users: /api/users, /api/users/{login}.

• Forge administration: /api/forges, /api/forges/{forge_id}.

• Agents: /api/agents, org agents. Agent tokens join the cluster.

• Registries: repo/org/global registry credentials.

• Organization directory and org settings outside secret CRUD.

• Queue pause/resume, log-level, and other instance admin controls.

• Repo move/rename, bulk repair-all, binary log download.

• User token mint/delete (/api/user/token) so this connector cannot mint a new PAT.

There is no arbitrary HTTP method/path passthrough.

Source provenance

Official latest stable release checked via the GitHub releases API: v3.20.1, released 29 Oct 2026. Linux amd64 binaries:

• https://github.com/woodpecker-ci/woodpecker/releases/download/v3.20.1/woodpecker-server_linux_amd64.tar.gz sha256 82dd50755bb198943521fa30e788ddd20de8179126d5abf9cb5de43e506e45a2

• https://github.com/woodpecker-ci/woodpecker/releases/download/v3.20.1/woodpecker-agent_linux_amd64.tar.gz sha256 cb8cf9028cde5a8eaf8612e9aec59a3e8636c1b2ab8d339cfafb770ebba5e3d8

Checksums from the release checksums.txt. Inventory from server/router/api.go plus server/router/router.go and cmd/server/openapi/docs.go at tag v3.20.1.

Pinned inventory hashes:

Other MCP servers

Read 11 Nov 2026. Pipeline trigger/cancel/restart/approve, cron, and secrets already exist in the strongest rivals. Those API operations are not unique here. Admin user/forge/agent coverage in ni-c/woodpecker-ci-mcp is broader; this connector excludes those on purpose.

Honest differences that still hold after those reads:

• Every mutation, including trigger, cancel, restart, approve, cron run, repair, activate, log delete, and secret create/update, needs boolean confirm: true and WOODPECKER_ALLOW_WRITES=true.

• Omitted or false confirm always returns a method/path/query/body preview with zero HTTP writes. Secret value in that preview is [redacted].

• ni-c already has elicitation plus confirm_token on a subset of writes, and WOODPECKER_READ_ONLY. It does not apply that guard to create_secret or trigger_pipeline. This connector's two-key gate is uniform; it is not a claim that ni-c lacks confirmation.

• Request-scoped redaction includes secret values supplied on create/update, percent-encoded any-case forms, and JSON-escaped forms. Nothing accumulates across requests.

• Route coverage is checked by the generator against a committed independent inventory. Public CI is offline.

• Six action-field toolsets instead of one tool per route.

• No automatic retries. Redirects are refused.

If a later rival adds the same two-key gate and dry-run preview on every write, that would no longer be unique.

Limitations

• Admin user, forge, agent, registry, and queue pause/resume stay out of the tool list. Use Woodpecker's own UI or ni-c if you need those.

• Global secret actions require an admin token. A non-admin token gets HTTP 403 from Woodpecker.

• GET /api/healthz is empty 204. The connector wraps that as { ok: true, status: 204 }.

• Live bad tokens from v3.20.1 are recorded in LIVE-CHECK.md. Unit tests still simulate 401, 422, and 429 with one fetch.

• The connector never starts or stops the user's Woodpecker. Isolated live scripts under /workspace/tools/woodpecker are throwaway only.

• A short credential (under 8 characters) that is spelled the same as an object key or a word in this connector's own preview envelope still appears there as that key or word. Values that contain it are redacted, and upstream free text is replaced. Use credentials of 8 or more characters.

Live check

See LIVE-CHECK.md for the checks that actually ran, including first-start notes. npm run live-check is not part of npm run ci.

npm run ci typechecks, lints, tests, and builds. node scripts/gen-operations.mjs --check reports 53 mapped routes, 70 excluded, 53 tool actions, and 123 spec routes.

Run unset DATABASE_URL, set WOODPECKER_URL, and set WOODPECKER_TOKEN or WOODPECKER_TOKEN_FILE. Then run npm run live-check. The script never prints the token.

License

MIT. Woodpecker itself is Apache-2.0. This connector only talks to the published REST API.