Skip to content
MCP server

Woodpecker CI

Read Woodpecker CI pipelines and logs and run builds, secrets and crons from an agent

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.4.0
Listing updated
2 days ago

About Woodpecker CI

Woodpecker CI is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

The failing-step log is the centrepiece: get_step_logs decodes the base64 chunks the Woodpecker API returns, restores line order, reports the exit code and returns the end of the log by default, since that is where the error usually sits.

Beyond reading, the server covers 71 tools against Woodpecker 3.18.0 across repositories, pipelines, secrets, registries, crons, organizations, users, agents, forges and the queue. Setting WOODPECKER_READ_ONLY=true registers only the 34 read tools, WOODPECKER_ALLOW_TOOLS=essential loads a curated eight, and WOODPECKER_DENY_TOOLS removes more. Twenty-four irreversible operations ask a person first through MCP elicitation, and agent tokens are redacted when listing agents.

It runs over stdio from npm or a container image and needs Node.js 24 or newer plus a Woodpecker personal access token, which carries the full authority of the account because the API has no scopes. For clients that cannot spawn local processes, the author points to a separate bridge, mcp-hub.

Install

Run in a terminal

claude mcp add woodpecker-ci-mcp --env WOODPECKER_URL='<WOODPECKER_URL>' --env WOODPECKER_TOKEN='<WOODPECKER_TOKEN>' -- npx -y @ni-c/woodpecker-ci-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "woodpecker-ci-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/woodpecker-ci-mcp"
      ],
      "env": {
        "WOODPECKER_URL": "<WOODPECKER_URL>",
        "WOODPECKER_TOKEN": "<WOODPECKER_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "woodpecker-ci-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/woodpecker-ci-mcp"
      ],
      "env": {
        "WOODPECKER_URL": "<WOODPECKER_URL>",
        "WOODPECKER_TOKEN": "<WOODPECKER_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "woodpecker-ci-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/woodpecker-ci-mcp"
      ],
      "env": {
        "WOODPECKER_URL": "<WOODPECKER_URL>",
        "WOODPECKER_TOKEN": "<WOODPECKER_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "woodpecker-ci-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/woodpecker-ci-mcp"
      ],
      "env": {
        "WOODPECKER_URL": "<WOODPECKER_URL>",
        "WOODPECKER_TOKEN": "<WOODPECKER_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "woodpecker-ci-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/woodpecker-ci-mcp"
      ],
      "env": {
        "WOODPECKER_URL": "<WOODPECKER_URL>",
        "WOODPECKER_TOKEN": "<WOODPECKER_TOKEN>"
      }
    }
  }
}

Configuration

  • WOODPECKER_URLRoot URL of the Woodpecker server, e.g. https://woodpecker.example.comRequired
  • WOODPECKER_TOKENPersonal access token from the Woodpecker user settingsRequired
  • WOODPECKER_READ_ONLYSet to true to register only the read tools (default: false)
  • WOODPECKER_ALLOW_TOOLSComma-separated tool names or list_* prefixes to register; 'essential' selects a curated preset (default: all tools)
  • WOODPECKER_DENY_TOOLSComma-separated tool names or list_* prefixes to remove from whatever the allow list left
  • WOODPECKER_INSECURE_TLSSet to true to accept a self-signed certificate from the Woodpecker server (default: false)
  • WOODPECKER_API_PREFIXPath of the API below the server root (default: /api; Crow CI 5 and later: /api/v1)
  • WOODPECKER_URLRoot URL of the Woodpecker server, e.g. https://woodpecker.example.comRequired
  • WOODPECKER_TOKENPersonal access token from the Woodpecker user settingsRequired
  • WOODPECKER_READ_ONLYSet to true to register only the read tools (default: false)
  • WOODPECKER_ALLOW_TOOLSComma-separated tool names or list_* prefixes to register; 'essential' selects a curated preset (default: all tools)
  • WOODPECKER_DENY_TOOLSComma-separated tool names or list_* prefixes to remove from whatever the allow list left
  • WOODPECKER_INSECURE_TLSSet to true to accept a self-signed certificate from the Woodpecker server (default: false)
  • WOODPECKER_API_PREFIXPath of the API below the server root (default: /api; Crow CI 5 and later: /api/v1)

Tools this server provides (3)

Taken from the project documentation; the running server may differ.

get_step_logs
Returns the decoded output of a failed step with its exit code, from the end of the log by default.
create_agent
Creates a Woodpecker agent and returns its token.
get_server_info
Reads server version information, falling back to the prefix when root routes differ.

What it does

Decoded step logs
Returns the failing step's output as ordered text with its exit code, tail first.
71-tool API coverage
Reaches repositories, pipelines, secrets, crons, agents, forges and the queue.
Read-only mode
One setting registers only the 34 read tools.
Tool allow and deny lists
Pick tools by name or list_* prefix, or use the curated essential preset of eight.
Confirmation for risky actions
Twenty-four irreversible operations ask a person via MCP elicitation.
Agent token redaction
Agent tokens are hidden when agents are listed.

Good for

  • Find out why a pipeline failed
  • Restart or cancel a build from a chat
  • Rotate a secret in a Woodpecker repository
  • Fix a cron schedule
  • Approve a pipeline blocked on review

Pricing

Open source

Prices change. Check woodpecker-ci-mcp.ni-c.de before you buy.

Woodpecker CI FAQ

What do I need to run it?

Node.js 24 or newer, the server URL in WOODPECKER_URL and a personal access token in WOODPECKER_TOKEN.

Can I stop it from changing anything?

Yes. WOODPECKER_READ_ONLY=true registers only the 34 read tools, so the write tools do not exist on the protocol.

Does it work with Crow CI?

The registry entry mentions WOODPECKER_API_PREFIX with /api/v1 for Crow CI 5 and later.

Can I use a self-signed certificate?

Set WOODPECKER_INSECURE_TLS=true to accept one.

How are agent tokens handled?

Listing agents redacts the token; create_agent still returns one because that is the only way to obtain it.

Is Woodpecker CI free?

Yes. Woodpecker CI is open source, so you can use and self-host it for free.

How do I add Woodpecker CI to Claude Code?

Run this command in your terminal: claude mcp add woodpecker-ci-mcp --env WOODPECKER_URL='<WOODPECKER_URL>' --env WOODPECKER_TOKEN='<WOODPECKER_TOKEN>' -- npx -y @ni-c/woodpecker-ci-mcp

What are the best alternatives to Woodpecker CI?

The closest alternatives to Woodpecker CI are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Woodpecker CI

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools