woodpecker-mcp

An MCP server for Woodpecker CI, generated from the Woodpecker OpenAPI spec with fastmcp and served over streamable HTTP.

The tool surface is a curated allowlist, not the full API: all the reads an agent needs to answer "why is my build red / stuck", plus exactly five write operations (trigger, restart, cancel, approve, decline pipeline). Everything else, repo/secret/cron/agent CRUD, forge and system administration, is not exposed.

Tools

Configuration

An MCP client may act as a different Woodpecker user by sending an X-Woodpecker-Token header; it overrides WOODPECKER_TOKEN for that request.

The server performs no authentication of its own, deploy it on a trusted network. token fields in upstream responses (e.g. agent registration tokens, which Woodpecker returns in cleartext to admin PATs) are redacted before reaching the client.

Running

Docker (streamable HTTP)

docker run -p 8000:8000 \
  -e WOODPECKER_SERVER=https://ci.example.com \
  -e WOODPECKER_TOKEN=... \
  ghcr.io/rtuszik/woodpecker-mcp:latest

The MCP endpoint is http://<host>:8000/mcp (streamable HTTP).

uvx (stdio)

The package is published to PyPI as woodpecker-ci-mcp. With WOODPECKER_MCP_TRANSPORT=stdio the server speaks MCP over stdin/stdout, so a client can spawn it directly. Register it with e.g. Claude Code:

claude mcp add woodpecker \
  --env WOODPECKER_SERVER=https://ci.example.com \
  --env WOODPECKER_TOKEN=... \
  --env WOODPECKER_MCP_TRANSPORT=stdio \
  -- uvx woodpecker-ci-mcp

or in a generic MCP client config:

{
  "mcpServers": {
    "woodpecker": {
      "command": "uvx",
      "args": ["woodpecker-ci-mcp"],
      "env": {
        "WOODPECKER_SERVER": "https://ci.example.com",
        "WOODPECKER_TOKEN": "...",
        "WOODPECKER_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

In stdio mode the per-request X-Woodpecker-Token override does not apply; the configured token is always used.

Development

uv sync            # install
uv run pytest      # tests
mise run check     # format, lint, typecheck, tests

The bundled spec lives at src/woodpecker_mcp/openapi.yaml; the allowlist that defines the tool surface is src/woodpecker_mcp/spec.py.