mcp-zuul — Claude Code MCP server for Zuul CI
Query Zuul CI to inspect failed builds, search logs, and check pipeline progress. Useful when a job fails and you need to locate the task or host behind it.
claude mcp add --env ZUUL_URL=<ZUUL_URL> --env ZUUL_DEFAULT_TENANT=<ZUUL_DEFAULT_TENANT> --env ZUUL_AUTH_TOKEN=<ZUUL_AUTH_TOKEN> --env ZUUL_USE_KERBEROS=<ZUUL_USE_KERBEROS> --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio mcp-zuul -- uvx mcp-zuulWhat mcp-zuul does
mcp-zuul connects an MCP client to Zuul CI. Its tools can parse build-failure details, search logs with regular expressions, and report live pipeline progress. It also includes tools for spotting flaky jobs and inspecting job dependencies. The project lists 48 tools, 5 prompts, and 3 resources.
For Claude Code, the setup command runs the server through uvx. Set ZUUL_URL to point it at a Zuul instance; configuration also covers tenant, auth token, Kerberos, and transport. Available transports include stdio, SSE, and streamable HTTP. Pipeline-changing operations are disabled when ZUUL_READ_ONLY=true; anomaly analysis requires LOGJUICER_URL.
A valid ZUUL_URL is essential: without it, the server has no Zuul instance to query. Enabling write operations allows changes to be enqueued, removed from the queue, or promoted.
What it helps with
- identify the failed task and host in a build
- search build logs with a regular expression
- check a job’s live pipeline progress
- find flaky jobs from recent build history
- inspect resolved job dependencies for a project and branch
Example prompts for the agent
- Analyze this Zuul build failure and identify the task, host, and error.
- Search the build logs for errors and show nearby context.
- Check the current progress of this change in the Zuul pipeline.
How to install mcp-zuul
Platform CLI
claude mcp add --env ZUUL_URL=<ZUUL_URL> --env ZUUL_DEFAULT_TENANT=<ZUUL_DEFAULT_TENANT> --env ZUUL_AUTH_TOKEN=<ZUUL_AUTH_TOKEN> --env ZUUL_USE_KERBEROS=<ZUUL_USE_KERBEROS> --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio mcp-zuul -- uvx mcp-zuulReplace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-zuul <command>
Platform CLI
codex mcp add mcp-zuul --env ZUUL_URL=<ZUUL_URL> --env ZUUL_DEFAULT_TENANT=<ZUUL_DEFAULT_TENANT> --env ZUUL_AUTH_TOKEN=<ZUUL_AUTH_TOKEN> --env ZUUL_USE_KERBEROS=<ZUUL_USE_KERBEROS> --env MCP_TRANSPORT=<MCP_TRANSPORT> -- uvx mcp-zuulReplace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-zuul <command>
Config file
{
"mcpServers": {
"mcp-zuul": {
"command": "uvx",
"args": [
"mcp-zuul"
],
"env": {
"ZUUL_URL": "<ZUUL_URL>",
"ZUUL_DEFAULT_TENANT": "<ZUUL_DEFAULT_TENANT>",
"ZUUL_AUTH_TOKEN": "<ZUUL_AUTH_TOKEN>",
"ZUUL_USE_KERBEROS": "<ZUUL_USE_KERBEROS>",
"MCP_TRANSPORT": "<MCP_TRANSPORT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-zuul <command>
Config file
{
"servers": {
"mcp-zuul": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-zuul"
],
"env": {
"ZUUL_URL": "<ZUUL_URL>",
"ZUUL_DEFAULT_TENANT": "<ZUUL_DEFAULT_TENANT>",
"ZUUL_AUTH_TOKEN": "<ZUUL_AUTH_TOKEN>",
"ZUUL_USE_KERBEROS": "<ZUUL_USE_KERBEROS>",
"MCP_TRANSPORT": "<MCP_TRANSPORT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-zuul <command>
Platform CLI
gemini mcp add -e ZUUL_URL=<ZUUL_URL> -e ZUUL_DEFAULT_TENANT=<ZUUL_DEFAULT_TENANT> -e ZUUL_AUTH_TOKEN=<ZUUL_AUTH_TOKEN> -e ZUUL_USE_KERBEROS=<ZUUL_USE_KERBEROS> -e MCP_TRANSPORT=<MCP_TRANSPORT> mcp-zuul uvx mcp-zuulReplace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-zuul <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-zuul
How do I install mcp-zuul in Claude Code?
Run claude mcp add mcp-zuul -- uvx mcp-zuul. Configure ZUUL_URL to connect it to your Zuul instance.
What does mcp-zuul do?
It gives MCP clients tools for examining Zuul CI failures, searching build logs, and checking pipeline status.
Can mcp-zuul use Kerberos authentication?
Yes. It supports Kerberos/SPNEGO authentication, and its configuration includes ZUUL_USE_KERBEROS.
