Zuul CI — build failure analysis, log search, pipeline status, and job configuration
Zuul CI MCP server that provides capabilities for build failure analysis, log search, pipeline status, and job configuration. It is associated with the Zuul CI ecosystem and is tagged for use with Ansible and CI/CD and DevOps workflows, and is offered as an MCP server.
🛠️ Key Features
Build failure analysis
Log search
Pipeline status
Job configuration
🚀 Use Cases
Diagnose CI build failures in Zuul pipelines
Search and investigate CI logs
Check pipeline status for Zuul CI runs
Retrieve or manage job configuration for Zuul CI
⚡ Developer Benefits
Clear mapping to Zuul CI tasks: failure analysis, logs, status, configuration
Fits into Model Context Protocol (MCP) server setups
Topics include devops, ci-cd, and mcp for discoverability
⚠️ Limitations
No additional capabilities or tool details are provided in the available source data.
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:
bash
claude mcp add zuul -e ZUUL_URL=https://your-zuul.example.com -- uvx mcp-zuul
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.
Read https://lobehub.com/mcp/imatza-rh-mcp-zuul/skill.md and follow the instructions to install the MCP server.
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.
Error handling — All tools return JSON, errors included. Network failures, auth issues, and invalid parameters produce {"error": "descriptive message"}. Tools never raise unhandled exceptions.
Tools
Builds & Failures
Tool
What it does
list_builds
Search builds by project, pipeline, job, change, result. Includes buildset_uuid for cross-referencing.
get_build
Full build details — nodeset, log URL, artifacts, error detail. Accepts url or uuid.
get_build_failures
Start here for failures. Structured task-level data from job-output.json — failed play, task, host, msg, rc, stderr/stdout. Accepts url or uuid.
diagnose_build
One-call failure diagnosis. Combines structured failures from job-output.json with targeted log context (fatal/FAILED lines with surrounding context from job-output.txt). Use instead of calling get_build_failures + get_build_log separately. Accepts url or uuid.
get_build_log
Read and search log files. Modes: summary (tail + error lines), full (paginated), grep (regex + context), start_line/end_line (exact range). Supports log_name for any file. Accepts url or uuid.
tail_build_log
Fastest failure check. Last N lines of a log (default 50, max 500). More token-efficient than get_build_log summary mode. Accepts url or uuid.
browse_build_logs
List log directory contents or fetch specific files (inventory, artifacts, must-gather). Max 512KB per file. Accepts url or uuid.
stream_build_console
Live console from RUNNING builds. Connects to Zuul WebSocket, returns last N lines (tail). For completed builds, use tail_build_log. Optional — requires pip install mcp-zuul[console].
Buildsets
Tool
What it does
list_buildsets
Search buildsets. Use include_builds=true to inline full build details (saves round-trips).
get_buildset
Full buildset with all builds and events. Accepts url or uuid.
Pipeline & Status
Tool
What it does
get_status
Live pipeline status — what's queued, running, with job progress and ETA. Filterable by pipeline and project.
get_change_status
Status for a change/PR/MR. In pipeline: live jobs with elapsed times. Not in pipeline: auto-fetches latest completed buildset. Accepts url or change.
Which pipelines and jobs are configured for a project.
list_projects
List all projects in a tenant with optional name filter.
get_config_errors
Check this when jobs aren't running. Configuration errors, missing refs, broken configs. Filterable by project.
get_freeze_jobs
Resolved job dependency graph for a pipeline/project/branch. Shows exactly which jobs will run with inheritance resolved.
get_freeze_job
Resolved job config after inheritance. Final merged nodeset, playbooks, variables, and timeout for a specific job. Answers "what will this job actually do?"
find_flaky_jobs
Analyze recent build history for intermittent failures. Computes pass/fail rate and flags jobs as flaky (>20% failure with mixed results).
get_build_times
Build duration trends with avg/min/max stats. Detect performance regressions or timeout-prone jobs.
get_job_durations
Batch avg/min/max duration for multiple jobs in one call. Designed for monitoring an entire pipeline chain without N separate calls.
check_health
Test API connectivity, auth status, and config. Triggers re-auth automatically if the Kerberos session expired.
get_tenant_info
Tenant capabilities — auth realms, job history support, websocket URL.
Infrastructure
Tool
What it does
list_nodes
Nodepool nodes with state (ready, in-use, building), provider, and label. Includes state summary.
list_labels
Available nodepool labels — what node types jobs can request.
list_semaphores
Resource locks with current holders and max capacity. Check when jobs wait unexpectedly.
list_autoholds
Active autohold requests — nodes held after failure for debugging.
get_autohold
Full details of a specific autohold request — held nodes, timing, project/job.
list_providers
Nodepool cloud providers with flavors (VM sizes), images, and labels.
list_images
Nodepool disk images with build status and provider upload state.
list_system_events
System events — config updates, reconfigurations, pipeline changes. Useful for "why did my job stop running?"
get_badge
CI status badge URL (SVG) for a project — embeddable in READMEs with Markdown snippet.
get_connections
Configured source connections — Gerrit, GitHub, GitLab instances with driver and hostname.
get_components
System components — schedulers, executors, mergers, web servers with state and version.
Write Operations
Pipeline-affecting operations — disabled by default (ZUUL_READ_ONLY=true). Set ZUUL_READ_ONLY=false to enable. Requires auth token or Kerberos. Autohold management (create/delete) is always available since it doesn't affect running pipelines.
Tool
What it does
enqueue
Enqueue a change or ref into a pipeline. Supports both change-based (check/gate) and ref-based (periodic) enqueue.
promote
Promote changes to the top of a pipeline queue. Use for urgent fixes when gate has a long queue.
reenqueue_buildset
Re-enqueue a buildset — reads project/pipeline/ref from a previous buildset and enqueues it again.
dequeue
Remove a change or ref from a pipeline. Destructive.
autohold_create
Create an autohold request — hold nodes after failure for debugging. Not gated by ZUUL_READ_ONLY.
autohold_delete
Delete an autohold request. Not gated by ZUUL_READ_ONLY.
Test Results & Log Analysis
Tool
What it does
get_build_test_results
Parse JUnit XML test results. Discovers test files via zuul-manifest.json, returns structured pass/fail/skip counts with failure details. Works with tempest, tobiko, and any JUnit XML output.
get_build_anomalies
ML-based log anomaly detection via LogJuicer. Compares failed logs against successful baselines. Requires LOGJUICER_URL.
Prompts
Pre-built prompt templates that pre-load context and guide analysis:
Prompt
What it does
debug_build
Fetches build details + structured failures, checks for flaky signal from recent history, then guides root cause analysis.
compare_builds
Loads two builds side-by-side with inline failure data for differential analysis — "why did this start failing?"
check_change
Determines live pipeline status or latest results for a change, with appropriate next steps.
tenant_health
Assesses overall tenant health — components, config errors, and node pool status in one view.
diagnose_queue_delay
Diagnoses why jobs are queued or delayed — checks nodes, semaphores, and system state.
Resources
Browsable context that clients can attach to conversations without tool calls:
Resource
URI Pattern
Build details
zuul://{tenant}/build/{uuid}
Job configuration
zuul://{tenant}/job/{name}
Project configuration
zuul://{tenant}/project/{org}/{repo}
Setup
MCP client configuration
All clients use the same JSON structure. Add to your client's MCP config file:
Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), and other MCP clients use the same format. GUI-based clients don't inherit your shell PATH - use the full path to uvx (run which uvx to find it).
Zuul base URL (e.g. https://softwarefactory-project.io/zuul)
ZUUL_DEFAULT_TENANT
No
—
Default tenant (saves passing tenant on every call)
ZUUL_AUTH_TOKEN
No
—
Bearer token for authenticated instances
ZUUL_USE_KERBEROS
No
false
Enable Kerberos/SPNEGO authentication
ZUUL_TIMEOUT
No
30
HTTP timeout in seconds
ZUUL_VERIFY_SSL
No
true
SSL certificate verification
MCP_TRANSPORT
No
stdio
Transport: stdio, sse, or streamable-http
MCP_HOST
No
127.0.0.1
HTTP server bind address (non-stdio transports)
MCP_PORT
No
8000
HTTP server port (non-stdio transports)
ZUUL_ENABLED_TOOLS
No
—
Comma-separated list of tools to enable (disables all others)
ZUUL_DISABLED_TOOLS
No
—
Comma-separated list of tools to disable (mutually exclusive with above)
ZUUL_READ_ONLY
No
true
Set to false to enable pipeline-affecting write operations (enqueue, promote, dequeue, reenqueue_buildset). Autohold management (create/delete) is always available.
LOGJUICER_URL
No
—
LogJuicer base URL for ML-based log anomaly detection
Token authentication
Pass ZUUL_AUTH_TOKEN via host environment — never hardcode tokens in config files (visible in ps output):
bash
export ZUUL_AUTH_TOKEN=<your-token>
For Docker, forward without a value to inherit from host:
"What jobs are configured for openstack-operator in the check pipeline?"
→ get_freeze_jobs(pipeline="check", project="openstack-k8s-operators/openstack-operator") → resolved job graph with dependencies.
Quick log tail
code
"Show me the last 30 lines of the build log"
→ tail_build_log(uuid="...", lines=30) → just the tail, minimal tokens.
What nodeset does my job use after inheritance?
code
"What nodeset and playbooks will deploy-job actually use?"
→ get_freeze_job(pipeline="check", project="org/repo", job_name="deploy-job") → resolved nodeset, playbooks, variables, timeout after all parent inheritance.
Development
bash
git clone https://github.com/imatza-rh/mcp-zuul.git
cd mcp-zuul
uv sync --extra dev
# Run locally
ZUUL_URL=https://softwarefactory-project.io/zuul uv run mcp-zuul
# Run tests
uv run pytest tests/ -v
# Lint and format
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
# Type check
uv run mypy src/mcp_zuul/
# Build Docker image
docker build -t mcp-zuul .
Contributions welcome. Please open an issue first to discuss significant changes.
bash
# Fork, clone, and install dev dependencies
uv sync --extra dev
# Make changes, then verify
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/mcp_zuul/
License
Apache-2.0
Install
Configuration
Environment variables
ZUUL_URL
Zuul base URL (e.g. https://softwarefactory-project.io/zuul)