imatza-rh/mcp-zuul

Debug build failures by asking questions, not clicking through web UIs. An MCP server for Zuul CI.
> If mcp-zuul saves you a debugging session, a ⭐ star helps others find it.
**One command, no install:**
48 tools, 5 prompts, 3 resources — covering builds, logs, pipelines, jobs, infrastructure, and live status. Works with Claude Code, Claude Desktop, Cursor, Codex, Windsurf, and any MCP-compatible client.
Why mcp-zuul?
| | mcp-zuul | Raw Zuul API | Zuul web UI |
|---|---|---|---|
| **Failure analysis** | Structured — task, host, error, rc | Raw JSON, parse yourself | Click through log pages |
| **Log search** | Regex + context lines + line ranges | Not available | Browser Ctrl+F |
| **Flaky detection** | Automatic pass/fail statistics | Manual query + calculate | Not available |
| **Test results** | Parsed JUnit XML with failure details | Not available | External link |
| **Anomaly detection** | ML-based via LogJuicer | Not available | Not available |
| **Live status** | Job progress, ETA, pre-failure alerts | Polling API | Manual refresh |
| **Multi-instance** | One config entry per Zuul | Different base URLs | Different browser tabs |
Quick Start
**uvx** (no install, recommended):
**pip**:
**Docker**:
**LobeHub** — send this to your AI agent:
See Setup for full configuration options including Kerberos and multi-instance.
Features
**Structured failure analysis** — get_build_failures parses Zuul's job-output.json and returns exactly which Ansible task failed, on which host, with error message, return code, and stderr. No log scrolling needed.
**Read any log file** — get_build_log isn't limited to job-output.txt. Pass log_name to read any file in the build's log directory (ci_script logs, ansible.log, deployment logs) with full grep, tail, and line-range support.
**Precise log navigation** — Jump to exact line ranges with start_line/end_line. After finding an error at line 6148, read lines 6130-6160 instead of scrolling through 200-line chunks.
**Smart grep** — Regex search with context lines. Auto-converts common shell-grep \| syntax to Python regex | so patterns like error\|failed\|timeout just work.
**Live pipeline awareness** — get_change_status returns live job progress with elapsed times, estimated completion, and pre-failure detection (pre_fail field). When the change isn't in pipeline, automatically fetches the latest completed buildset.
**Tool filtering** — Reduce LLM tool-selection noise with ZUUL_ENABLED_TOOLS or ZUUL_DISABLED_TOOLS. Only expose the tools your workflow needs — the rest are removed from the server entirely.
**URL-based input** — Paste a Zuul build URL directly. Tools auto-parse the tenant and UUID from URLs like https://zuul.example.com/t/tenant/build/abc123 — no manual extraction needed.
**Flaky job detection** — find_flaky_jobs analyzes recent build history and computes pass/fail statistics to identify intermittent failures automatically.
**Job dependency graph** — get_freeze_jobs returns the fully-resolved job graph for a pipeline/project/branch, showing all jobs with their dependencies after inheritance resolution.
**Kerberos/SPNEGO auth** — First-class support for Zuul instances behind OIDC + Kerberos. Drives the full SPNEGO redirect chain automatically. Session cookies persist and re-authenticate transparently on expiry.
**Streamable HTTP transport** — Run as a persistent HTTP server with MCP_TRANSPORT=streamable-http for remote/shared deployment. Supports stdio (default), SSE, and streamable-http.
**Write operations** — Enqueue/dequeue/promote changes and re-enqueue buildsets. Pipeline-affecting tools are disabled by default (ZUUL_READ_ONLY=true) and removed from the server entirely so LLMs don't even see them. Autohold management (create/delete) is always available since it doesn't affect running pipelines.
**LogJuicer integration** — get_build_anomalies uses ML-based log analysis to find unusual lines by comparing failed logs against successful baselines. Optional — requires LOGJUICER_URL.
**Token-efficient output** — All responses strip None values and use compact formatters. tail_build_log returns just the last N lines — the fastest way to check why a build failed.