NO
Developer Tools

Nomad MCP Server: Cluster Management Tools

Manage Nomad clusters with the MCP server and its tools for deployment, monitoring, and configuration at scale.

View on GitHub
Quick Install
npx -y @kocierik/mcp-nomad

Overview

The Nomad MCP Server is a lightweight management layer for HashiCorp Nomad clusters. It provides tools and APIs to simplify deployment orchestration, configuration propagation, and operational monitoring across one or more Nomad servers. The project is intended to help teams manage cluster-wide policies, rollouts, and day‑to‑day tasks at scale without having to build bespoke automation for every environment.

MCP Server acts as a centralized control plane that interacts with Nomad’s HTTP API and cluster metadata. It can be deployed as a single binary or container and exposes a small set of management endpoints plus command‑line utilities. The server is useful for teams running multiple Nomad clusters, practicing progressive delivery (canaries/blue‑green), or who want standardized configuration and auditability across environments.

Features

  • Centralized API for deploying and managing Nomad jobs across clusters
  • Declarative configuration sync for Nomad ACLs, variables, and runtime settings
  • Rollout helpers: canary, blue/green and batch deployment primitives
  • Cluster health and job monitoring with simple health endpoints and metrics
  • Job templating and HCL generation to automate repetitive deployments
  • Snapshot and restore features for job definitions and cluster configuration
  • CLI client (mcpctl) for scripting and automation
  • Lightweight storage backend with support for BoltDB or Postgres

Installation / Configuration

Install by running a Docker container or downloading the prebuilt binary. Example Docker run:

# Run MCP Server in Docker
docker run -d \
  --name mcp-server \
  -p 8080:8080 \
  -e NOMAD_ADDR=http://nomad.example:4646 \
  -e MCP_STORAGE=bolt \
  -v /var/lib/mcp:/data \
  kocierik/mcp-nomad:latest

Or download and run the binary:

# Linux binary
wget https://github.com/kocierik/mcp-nomad/releases/latest/download/mcp-server-linux-amd64
chmod +x mcp-server-linux-amd64
./mcp-server-linux-amd64 --listen ":8080" --nomad-addr "http://nomad.example:4646" --storage "bolt:/var/lib/mcp/mcp.db"

Common configuration options (flags or environment variables):

  • –listen / MCP_LISTEN: address and port to bind (default :8080)
  • –nomad-addr / NOMAD_ADDR: Nomad HTTP API address
  • –nomad-token / NOMAD_TOKEN: Nomad ACL token (optional)
  • –storage / MCP_STORAGE: storage backend (bolt or postgres) and DSN
  • –tls-cert / –tls-key: TLS files to serve HTTPS

Example systemd unit:

[Unit]
Description=MCP Nomad Server
After=network.target

[Service]
ExecStart=/usr/local/bin/mcp-server --listen ":8080" --nomad-addr "http://127.0.0.1:4646" --storage "bolt:/var/lib/mcp/mcp.db"
Restart=on-failure

[Install]
WantedBy=multi-user.target

Available Tools / Resources

  • mcp-server: HTTP server exposing management endpoints and metrics.
  • mcpctl: CLI for interacting with MCP Server (deploy, promote, rollback).
  • HCL templating: helper library/CLI to produce Nomad job files from templates.
  • Metrics endpoint: /metrics compatible with Prometheus.
  • API endpoints:
    • GET /clusters - list managed Nomad clusters
    • POST /deploy - submit a job template for rollout
    • POST /promote - promote canary to stable
    • GET /jobs/:id/status - job health and rollout state

Default ports and endpoints:

ComponentDefault PortPurpose
MCP Server8080API & metrics
Prometheus9090*external (optional)

(*Prometheus is external; MCP exposes /metrics for scraping.)

Use Cases

  • Multi‑cluster rollout coordination: Use MCP Server to submit a single job template and have it deployed to multiple Nomad clusters in a controlled sequence. This reduces drift and centralizes rollout status.

    • Example: Deploy version 2.0 to staging cluster A, run smoke tests, then promote to production clusters.

  • Canary and progressive delivery: Deploy a canary allocation using mcpctl, observe metrics and logs, then promote or rollback via a single API call.

    • Command example:
      mcpctl deploy --template web-service.hcl --strategy canary --canary-count 1
mcpctl promote --job web-service --from canary

  • Configuration synchronization: Store ACL policies, Nomad variables, or job templates in MCP storage and sync them to selected clusters to maintain consistency across teams.

  • Backup and restore of job definitions: Periodically snapshot job definitions and cluster config via the server to ensure recoverability and audit history.

  • Monitoring and automation: Scrape /metrics with Prometheus and trigger automated workflows (e.g., rollback) when health checks fail.

Getting Started Tips

  1. Start with a single, non-production Nomad cluster to experiment with deployments and rollouts.
  2. Enable a read‑only Nomad token for MCP Server during initial tests to avoid accidental destructive operations.
  3. Use the mcpctl CLI for simple scripting and CI/CD integration; integrate with your CI pipeline to run deploy/promote commands.
  4. Scrape /metrics and set up alerting for rollout failures and cluster health regressions.

The MCP Server is designed to be a practical, minimal control plane for teams using Nomad. Its CLI and API primitives aim to standardize common cluster management tasks without replacing Nomad’s native APIs.

Tags:developer-tools