Skip to content

README.md

Latest commit

 

History

History
120 lines (87 loc) · 3.05 KB

README.md

File metadata and controls

120 lines (87 loc) · 3.05 KB

nomad-mcp

nomad-mcp is a read-only MCP server for HashiCorp Nomad built with the official Go MCP SDK and the official Nomad API client.

Note

This project was developed via agentic / vibe coding

Scope

The initial implementation targets stdio transport and read-only inspection workflows.

Supported tools:

  • get_cluster_status
  • list_regions
  • list_namespaces
  • list_nodes
  • get_node
  • list_jobs
  • get_job
  • get_job_scale_status
  • get_job_evaluations
  • get_job_allocations
  • get_job_services
  • list_deployments
  • get_deployment
  • list_allocations
  • get_allocation
  • get_allocation_checks

list_jobs now includes each job's meta map and a stable meta_summary string so clients can answer discovery questions from a single tool call.

Supported resources:

  • nomad://cluster/summary
  • nomad://jobs/{namespace}/{job_id}/summary
  • nomad://jobs/{namespace}/{job_id}/spec
  • nomad://jobs/{namespace}/{job_id}/evaluations
  • nomad://allocs/{allocation_id}/status
  • nomad://allocs/{allocation_id}/checks
  • nomad://allocs/{allocation_id}/logs/{task_name}/{stream}
  • nomad://nodes/{node_id}/status
  • nomad://nodes/{node_id}/allocations
  • nomad://deployments/{deployment_id}
  • nomad://evaluations/{evaluation_id}

Supported prompts:

  • debug_allocation
  • explain_evaluation
  • diagnose_deployment
  • investigate_node
  • explain_job

Configuration

The server uses Nomad's standard environment variables through github.com/hashicorp/nomad/api.DefaultConfig().

Operational logs are emitted with Go's log/slog package to stderr, so they do not interfere with the MCP stdio protocol on stdout. Set NOMAD_MCP_LOG_LEVEL to debug, info, warn, or error to adjust verbosity.

Common variables:

  • NOMAD_ADDR
  • NOMAD_TOKEN
  • NOMAD_NAMESPACE
  • NOMAD_REGION
  • NOMAD_CACERT
  • NOMAD_CAPATH
  • NOMAD_CLIENT_CERT
  • NOMAD_CLIENT_KEY
  • NOMAD_TLS_SERVER_NAME
  • NOMAD_SKIP_VERIFY

Per-tool inputs can override namespace, region, pagination, filtering, and stale-read behavior where the underlying Nomad endpoint supports those options.

For discovery-style questions, prefer list_jobs first. The filter input accepts native Nomad filter expressions, for example:

  • Name matches "financial"
  • Meta.department == "financial"

That makes questions like "what financial jobs are there" answerable without post-processing MCP output with shell tools.

Run

Build the server:

go build ./cmd/nomad-mcp

Run it directly over stdio:

./nomad-mcp

Docker

Build the image:

docker build -t nomad-mcp .

Run it over stdio:

docker run --rm -i \
	-e NOMAD_ADDR=https://nomad.example.com \
	-e NOMAD_TOKEN=... \
	nomad-mcp

The container uses the same NOMAD_* environment variables as the local binary.

Notes

  • This MVP does not perform writes.
  • This MVP does not expose event streams or blocking-query watch semantics.
  • Allocation logs are exposed only as bounded static tails through resources and prompts. Follow mode and filesystem browsing are still excluded.