# Woodpecker CI

> Woodpecker CI is an open-source MCP server for developer tools. Read Woodpecker CI pipelines and logs and run builds, secrets and crons from an agent. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://woodpecker-ci-mcp.ni-c.de
- **Repository:** https://github.com/ni-c/woodpecker-ci-mcp
- **MCP Registry name:** io.github.ni-c/woodpecker-ci-mcp
- **Categories:** developer tools
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

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

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/woodpecker-ci
