# mcp-zuul

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 21
- Author: imatza-rh
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/imatza-rh/mcp-zuul
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-zuul

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `ZUUL_URL`, `ZUUL_DEFAULT_TENANT`, `ZUUL_AUTH_TOKEN`, `ZUUL_USE_KERBEROS`, `MCP_TRANSPORT`, `ZUUL_ENABLED_TOOLS`, `ZUUL_DISABLED_TOOLS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-zuul
```
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>

### Codex

**Platform CLI**
```bash
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-zuul
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-zuul
```
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>

## When to use it
- 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
- 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.

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md