Woodpecker CI
Read Woodpecker CI pipelines and logs and run builds, secrets and crons from an agent
- 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-mcpAdd 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.comRequiredWOODPECKER_TOKENPersonal access token from the Woodpecker user settingsRequiredWOODPECKER_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 leftWOODPECKER_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.comRequiredWOODPECKER_TOKENPersonal access token from the Woodpecker user settingsRequiredWOODPECKER_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 leftWOODPECKER_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

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools