Skip to main content
Glama
Sign In
hydra-mcp

hydra-mcp

by slopinger
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

hydra-mcp

An MCP server for Hydra, the Nix continuous integration server. It lets an agent look at projects, jobsets, evaluations, builds, build steps, logs and the queue, and (with an account) trigger evaluations, restart, cancel or bump builds and create or edit projects and jobsets. It works with NixOS Hydra and its forks (Lix's Hydra), and can talk to several instances at once.

Tools

Tool

What

list_instances

Configured instances, the default, whether each can log in

list_projects, get_project

Projects; a project's jobsets with error flags and build counts

get_jobset

Configuration, evaluation state, eval/fetch errors, recent evaluations

list_evals, get_eval

Evaluations (inputs/flake rev, counts), builds filtered by status

get_build

Status, timing, derivation, outputs, products, metrics; failed, running and newest build steps (steps="all" for every one)

get_build_log

Tail of a build's log or of one build step (e.g. the failed dependency)

get_job

A job's build in the newest evaluation and its latest successful build

get_queue

Queue size, top of the queue, running builds

search

Projects, jobsets, jobs and builds by name or store path

trigger_evaluation

Schedule a jobset evaluation (/api/push)

restart_build, cancel_build, bump_build

Build actions

manage_eval

Restart failed/aborted builds of an evaluation, cancel or bump them

put_project, put_jobset

Create, or change only the given fields of, a project or jobset

There is also a debug_jobset prompt. Read tools work anonymously on public instances; write tools log in with the configured account and need the matching Hydra role (create-projects, restart-jobs, cancel-build, bump-to-front, or project ownership).

Notes on Hydra's API that the tools handle for you: boolean fields of projects and jobsets are true whenever the key is present (so put_* omits false flags rather than sending 0), latest URLs mean the latest successful build, build steps only exist on the HTML build page, and POST requests need a Referer/Origin matching the instance.

Related MCP server: MCP Jenkins

Configuration

~/.config/hydra-mcp/config.toml (or $HYDRA_MCP_CONFIG, or --config):

default = "nixos"

[instances.nixos]
url = "https://hydra.nixos.org"

[instances.mine]
url = "https://hydra.example.org"
username = "alice"                         # or username_file = "~/.secrets/hydra/username"
password_file = "~/.secrets/hydra/password"

Passwords are only read from files, at login time; they never appear in the config, the process arguments or tool results. URLs must be HTTPS (plain HTTP only for loopback), and the client never follows redirects to another host. The file is re-read whenever it changes (including a Home Manager switch that repoints its symlink), so no restart is needed. Without a config file, HYDRA_URL (default https://hydra.nixos.org), HYDRA_USERNAME and HYDRA_PASSWORD_FILE describe a single instance.

Running

nix run github:slopinger/hydra-mcp            # stdio
uv run hydra-mcp --transport streamable-http   # http://127.0.0.1:8002/mcp, no authentication

Claude Code: claude mcp add -s user hydra -- nix run github:slopinger/hydra-mcp, or point command at a built result/bin/hydra-mcp. Logs, descriptions and error messages come from builds and other users: clients should treat them as data, not instructions.

Development

nix develop         # editable environment with pytest
uv run pytest       # offline tests: config, client against a mock Hydra, MCP stdio handshake
uv run pytest -m live   # a few read-only calls to a real instance (HYDRA_LIVE_URL)
nix build && nix flake check

MIT licensed.

Available Tools

18 tools
bump_buildB

Move a queued build to the front of the queue (needs bump rights).

Inputs: build_id (required), instance. Returns: object

cancel_buildA
DestructiveIdempotent

Cancel a queued or running build (needs cancel rights). Confirm with the user first.

Inputs: build_id (required), instance. Returns: object

get_buildA
Read-onlyIdempotent

Get a build: status, timing, derivation, outputs, products, metrics and its build steps.

steps="relevant" (default) lists failed and running steps plus the newest few; "all" lists every step (large for big closures). Failed steps name the dependency behind "dependency failed".

Inputs: build_id (required), steps, instance, recent_steps. Returns: object

get_build_logA
Read-onlyIdempotent

Get the last lines of a build's log, or of one of its build steps (e.g. the failed dependency).

Inputs: build_id (required), step, instance, tail_lines. Returns: object

get_evalA
Read-onlyIdempotent

Get an evaluation: its inputs, build counts by status and its builds (filter by status).

status: all, failed (finished, not succeeded), succeeded or queued (not finished yet).

Inputs: eval_id (required), limit, status, instance. Returns: object

get_jobB
Read-onlyIdempotent

Get a job's build in the jobset's newest evaluation (any status) and its latest successful build.

Inputs: job (required), jobset (required), project (required), system, +1 more. Returns: object

get_jobsetB
Read-onlyIdempotent

Get a jobset's configuration, evaluation state and errors, plus its most recent evaluations.

Inputs: jobset (required), project (required), instance, recent_evals. Returns: object

get_projectA
Read-onlyIdempotent

Get one project's settings and the state of each of its jobsets (errors, last evaluation).

Inputs: project (required), instance. Returns: object

get_queueB
Read-onlyIdempotent

Get the build queue (highest priority first), its size by jobset, and the builds running right now.

Inputs: limit, instance. Returns: object

list_evalsA
Read-onlyIdempotent

List a jobset's evaluations, newest first, one page at a time.

Inputs: jobset (required), project (required), page, instance. Returns: object

list_instancesA
Read-onlyIdempotent

List the configured Hydra instances, the default one and whether each can log in for write tools.

Inputs: no named parameters. Returns: object

list_projectsB
Read-onlyIdempotent

List the projects of a Hydra instance with their jobsets.

Inputs: instance. Returns: object

manage_evalA
DestructiveIdempotent

Restart an evaluation's failed or aborted builds, cancel its queued builds, or bump them to the front.

cancel is destructive: confirm with the user first.

Inputs: action (required), eval_id (required), instance. Returns: object

put_jobsetA
Idempotent

Create a jobset, or change the given fields of an existing one (others keep their values).

Give flake for a flake jobset, or nix_expression_input/path plus inputs for a legacy one. Needs project ownership (or admin). New jobsets default to enabled, visible, no email, 300 s polling.

Inputs: jobset (required), project (required), flake, state, +11 more. Returns: object

put_projectA
Idempotent

Create a project, or change the given fields of an existing one (others keep their values).

Creating needs the create-projects role; editing needs project ownership.

Inputs: project (required), enabled, visible, homepage, +3 more. Returns: object

restart_buildB

Re-queue a finished build (needs restart rights).

Inputs: build_id (required), instance. Returns: object

searchB
Read-onlyIdempotent

Search projects, jobsets, jobs and builds (by name, output or derivation path).

Inputs: query (required), instance. Returns: object

trigger_evaluationA

Ask Hydra to evaluate a jobset soon (needs restart rights on the project). force re-evaluates even if inputs are unchanged.

Inputs: jobset (required), project (required), force, instance. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.6/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools target a clearly distinct resource+action pair (get_project vs get_jobset vs get_eval vs get_build), so an agent can usually pick correctly. There is real overlap between the single-build actions (cancel_build, bump_build, restart_build) and manage_eval, which bundles the same restart/cancel/bump operations at evaluation scope; the descriptions distinguish granularity, but the boundary requires careful reading.

    Naming Consistency4/5

    Predominantly consistent snake_case verb_noun (list_projects, get_build, trigger_evaluation, restart_build). Minor deviations: bare 'search' lacks a noun, and put_project/put_jobset use 'put' (upsert) where the rest use get/list/create-style verbs, though create+update-in-one is documented.

    Tool Count4/5

    18 tools is slightly on the heavy side but each maps to a genuine object in Hydra's model (instances, projects, jobsets, evals, builds, steps, queue), and no tool looks redundant filler. It could be trimmed by folding build-level cancel/bump/restart into manage_eval.

    Completeness4/5

    Strong read/write coverage across the whole lifecycle: discovery, project/jobset upsert, evaluation triggering and management, build inspection, logs, queue, and search. Notable gaps are deletions (no delete_project, delete_jobset, or delete_build) and any jobset/job-level disabling, which are reachable in Hydra but not exposed here.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP Jenkins

      microtechos
      A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to inspect and operate a Jenkins instance — discovering jobs, views, nodes, and plugins; reviewing build chains, parameters, last-build status, console output, test reports, and artifacts; and triggering builds, stopping runs, or answering pipeline inputs. It connects over stdio, SSE, or streamable HTTP with optional credentials, read-only mode, and a credential-free health endpoint.
      31
      1
      MIT

    • MCP Jenkins

      Adrian8211
      F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to securely interact with Jenkins through its API, exposing tools for inspecting items, nodes, views, queues, and builds, reading console output, test reports, and artifacts, managing plugins, and triggering, stopping, or approving pipeline builds, including executing Groovy scripts. Supports stdio, SSE, and streamable-HTTP transports with configurable authentication, SSL verification, and a read-only mode.
      -

    • MCP Jenkins Server

      ahmetmonti
      F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI models to securely inspect and operate Jenkins through tools for jobs, builds, queue items, nodes, views, plugins, artifacts, pipeline inputs, and Groovy script execution. Supports stdio, SSE, and streamable-HTTP transports with configurable authentication and a read-only mode.
      -