woodpecker-mcp/README.md

Woodpecker CI MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Woodpecker CI. Debug pipeline failures, analyze build logs, and troubleshoot CI/CD configurations with AI assistance.

This is a Go implementation of j04n-f/woodpecker-mcp built with mark3labs/mcp-go. It speaks the MCP protocol over stdio (JSON-RPC) and talks to the Woodpecker CI REST API.

Requirements

• Go 1.26+

Build

go build -o woodpecker-mcp ./cmd/woodpecker-mcp

The version embedded in the initialize handshake can be set at build time:

go build -ldflags "-X gitea.fe.kaien.ru/kaien/woodpecker-mcp/internal/version.Version=v1.2.3" -o woodpecker-mcp ./cmd/woodpecker-mcp

Configuration

Environment variable	Required	Description
WOODPECKER_URL	yes	Base URL of your Woodpecker CI instance, e.g. https://woodpecker.example.com
WOODPECKER_TOKEN	yes	Personal access token (profile icon → "CLI & API")

The server refuses to start with a missing or invalid configuration.

Transports

The server speaks MCP over stdio by default (the standard mode for local MCP clients such as Claude Desktop, Cursor, etc.). A remote Streamable HTTP transport is also available:

Flag	Default	Description
--transport	stdio	stdio or http
--listen	:8080	HTTP listen address (used with --transport=http)

# stdio (default)
woodpecker-mcp

# remote Streamable HTTP on :8080 (endpoint /mcp)
woodpecker-mcp --transport=http --listen=:8080

The HTTP endpoint is http://<host>:8080/mcp (Streamable HTTP, MCP spec 2025-06-18). No authentication is enforced — run it inside your trusted network only. In Docker, expose the port when using HTTP mode:

docker run -i --rm -p 8080:8080 \
  -e WOODPECKER_URL=https://your-woodpecker-instance.com \
  -e WOODPECKER_TOKEN=your-token-here \
  your-registry/woodpecker_mcp/woodpecker_mcp --transport=http

Deployment (Kubernetes)

The repository ships a k8s-deploy.yaml (Service + Deployment) that runs the binary in HTTP mode (--transport=http) on port 8080.

• Namespace: mcp-servers
• Service: woodpecker-mcp (ClusterIP, 8080 -> 8080); in-cluster URL: http://woodpecker-mcp.mcp-servers:8080/mcp
• Image: registry.be.kaien.ru/woodpecker_mcp/woodpecker_mcp:$CI_COMMIT_SHA (rendered by envsubst in CI; every commit triggers a rollout via the deployment.l-ai/commit annotation)
• Secrets: WOODPECKER_TOKEN comes from the SealedSecret woodpecker-mcp-sealed.yaml (name woodpecker-mcp, ns mcp-servers). WOODPECKER_URL is not secret and is set as a plain env var (https://ci.be.kaien.ru/ — a trailing slash is harmless, the config trims it before appending /api).

To reseal the token after rotation, run kubeseal and replace spec.encryptedData.WOODPECKER_TOKEN:

echo -n 'your-token' | kubeseal --namespace mcp-servers --name woodpecker-mcp --raw

Woodpecker CI secrets required by the pipeline: SSH_PRIVATE_KEY, DEPLOY_HOST, DEPLOY_USER (deploy step) plus ZOT_USERNAME, ZOT_PASSWORD (build step).

MCP Client Setup

Add to your MCP client configuration:

{
  "woodpecker-ci": {
    "command": "woodpecker-mcp",
    "env": {
      "WOODPECKER_TOKEN": "your-token-here",
      "WOODPECKER_URL": "https://your-woodpecker-instance.com"
    }
  }
}

API Reference

Tool	Description	Parameters
search_repository	Find repository by name	name (e.g. "owner/repo")
get_repository_by_id	Get repository details by ID	repoId
list_repositories	List all repositories	Optional: page, perPage, active, trusted
list_pipelines	List repository pipelines	repoId, optional: page, perPage, before, after
get_pipeline	Get detailed pipeline info	repoId, number
get_pipeline_config	View pipeline configuration	repoId, number
get_step_logs	Get logs for debugging	repoId, number, stepId

All tools are read-only (GET requests only). Errors are returned as structured JSON with a status-aware description and suggested next steps.

Development

go vet ./...
go test -race ./...

Examples

Debug a Failed Pipeline

AI: Can you check why pipeline #42 failed for repository owner/project?

Analyze Build Performance

AI: Show me the recent pipeline performance for my main repository and identify any bottlenecks.

Configuration Review

AI: Review the pipeline configuration for repository owner/project and suggest improvements.

Project Layout

cmd/woodpecker-mcp/  entry point: config load, signal handling, stdio transport
internal/config/     environment configuration and validation
internal/server/     MCP server assembly
internal/tools/      MCP tool definitions and handlers (repositories, pipelines, logs)
internal/woodpecker/ Woodpecker CI REST API client (types, client, error contexts)
internal/version/    server name and version

License

MIT License