Purpose
mcp-zuul is an MCP (Model Context Protocol) server for Zuul CI, used to debug build failures, search logs, manage pipelines, and monitor jobs by asking questions in natural language, replacing the approach of repeatedly clicking through the Web UI to investigate. It can be used with Claude Code, Claude Desktop, Cursor, Codex, Windsurf, and any MCP-compatible client.
Main capabilities
- Covers builds, logs, pipelines, jobs, infrastructure, and real-time status, providing 48 tools, 5 prompts, and 3 resources.
- Structured failure analysis: get_build_failures parses Zuul's job-output.json and returns the specific failed Ansible task, the host it was on, the error message, the return code, and stderr.
- Read any log file: get_build_log is not limited to job-output.txt; via log_name it can read any file in the build log directory (such as ci_script logs, ansible.log, deployment logs), with full grep, tail, and line range support.
- Precise log navigation: jump to a specified line range via start_line / end_line.
- Smart grep: supports regex search and context lines, and automatically converts the common shell grep | syntax to Python regex |.
- Real-time pipeline awareness: get_change_status returns real-time job progress, elapsed time, estimated completion time, and pre-failure detection (the pre_fail field); when a change is not in the pipeline, it automatically fetches the most recent completed buildset.
- Tool filtering: via ZUUL_ENABLED_TOOLS or ZUUL_DISABLED_TOOLS, reduce the noise in the LLM's tool selection and expose only the tools the workflow needs.
- Supports directly pasting a Zuul build URL, automatically parsing the tenant and UUID.
- Flaky job detection: find_flaky_jobs analyzes recent build history and calculates pass/fail statistics.
- Job dependency graph: get_freeze_jobs returns the complete job graph after inheritance resolution andits dependencies.
- Kerberos/SPNEGO authentication: supports Zuul instances behind OIDC + Kerberos, automatically following the full SPNEGO redirect chain, with session cookies persisted and transparent re-authentication on expiration.
- Streamable HTTP transport: run as a persistent HTTP server via MCP_TRANSPORT=streamable-http, for remote/shared deployments; supports stdio (default), SSE, and streamable-http.
- Write operations: can enqueue/dequeue/promote changes and re-enqueue buildsets. Tools that affect the pipeline are disabled by default (ZUUL_READ_ONLY=true) and are completely removed from the server; autohold management (create/delete) is always available because it does not affect a running pipeline.
- LogJuicer integration: get_build_anomalies uses machine learning-based log analysis to find anomalous lines by comparing failure logs against a success baseline; this feature is optional and requires configuring LOGJUICER_URL.
- Token-efficient output: all responses remove None values and use compact formatting; tail_build_log returns only the last N lines.
- Error handling: all tools return JSON (including errors); network failures, authentication issues, and invalid parameters return {"error": "descriptive message"} and do not throw unhandled exceptions.
Usage
- No installation required; run with a single command (uvx recommended): uvx mcp-zuul (see the official repository and Setup documentation for the full command).
- Can also be installed: pip install mcp-zuul.
- MCP client configuration uses a unified JSON structure, added to the client's MCP configuration file; for Claude Code it is under mcpServers in ~/.claude.json, and Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), etc. use the same format. GUI clients do not inherit the shell PATH, so the full path to uvx must be used (obtained via which uvx).
- Environment variable configuration: supports via ZUUL_AUTH_TOKEN passes in a token for authentication; Kerberos/SPNEGO requires a valid Kerberos ticket (kinit) and the gssapi package; on Linux, install the system packages first, then install with mcp-zuul[kerberos]; multiple instance configurations are supported.
- Docker image: ghcr.io/imatza-rh/mcp-zuul; in Docker environments, host environment variables can be inherited via valueless forwarding, and in Kerberos scenarios the ticket cache can be mounted.
- The provided prompt templates can preload context and guide analysis; resources can be browsed for clients to attach to a conversation without calling tools.
Applicable Scenarios
- Debugging build failures: list_builds → get_build_failures to obtain the root cause (job name, error, return code).
- Drilling into logs: browse_build_logs to find the log file, then use get_build_log with grep and context to locate errors.
- Precisely read log fragments by line number.
- View real-time pipeline status or the most recently completed buildset.
- Compare multiple build results in the same pipeline (list_builds → get_buildset).
- Paste a Zuul URL directly to automatically parse the tenant and UUID.
- Troubleshoot why a job did not run (get_config_errors).
- Check node availability (list_nodes, list_labels).
- Detect flaky jobs (find_flaky_jobs).
- View the jobs a project runs (get_freeze_jobs) and the inherited node set (get_freeze_job).
- Use tail_build_log to quickly view the cause of a build failure with minimal tokens.
Limitations
- The gssapi supported by Kerberos has no precompiled wheel on Linux; it must be compiled from source and system dependencies installed first (such as krb5-config, Python.h); macOS and Windows have precompiled wheels and require no additional packages.
- Pipeline-affecting tools among write operations are disabled by default (ZUUL_READ_ONLY=true); you must explicitly set ZUUL_READ_ONLY=false and need an authentication token or Kerberos.
- LogJuicer integration is an optional feature and requires LOGJUICER_URL to be configured.
- Tokens should not be hardcoded in configuration files (they will appear in ps output); they should be passed in via host environment variables.
- No further information is currently provided regarding billing, pricing, platform support scope, and performance metrics.
