nomad-mcp

What is mcp-nomad?

mcp-nomad is a server that provides a set of tools for managing Nomad clusters through the Model Context Protocol (MCP). It is written in Go and allows for programmatic interaction with Nomad, offering a wide range of functionalities for cluster management.

How to use mcp-nomad?

mcp-nomad can be used in several ways:

• Browse with Inspector: Use npx @modelcontextprotocol/inspector npx @kocierik/mcp-nomad to browse with the Inspector.
• Use with Claude: Integrate with Claude by configuring claude_desktop_config.json or using installation tools like Smithery (npx -y @smithery/cli install @kocierik/mcp-nomad --client claude) or mcp-get (npx @michaellatman/mcp-get@latest install @kocierik/mcp-nomad).
• Pre-built from NPM: Install globally via npm install -g @kocierik/mcp-nomad.
• From GitHub Releases: Download the pre-built binary.
• Building from Source: Build from source using go get github.com/kocierik/mcp-nomad and go install github.com/kocierik/mcp-nomad.
• Using Docker: Run as a Docker container, with specific commands for Linux, macOS, and Windows.

Configuration options include specifying the Nomad server address (-nomad-addr), port for SSE server (-port), and transport type (-transport). Environment variables like NOMAD_ADDR and NOMAD_TOKEN can also be set.

Key Features of mcp-nomad

mcp-nomad offers extensive features for managing Nomad clusters, categorized as follows:

• Job Management: List, get details, run, stop, update, dispatch, revert, set stability, create evaluations/plans, force new periodic instances, scale task groups, and list services.
• Deployment Management: List and get deployment details.
• Namespace Management: List, create, and delete namespaces.
• Node Management: List, get details, drain, and set eligibility for nodes.
• Allocation Management: List, get details, and retrieve logs for allocations and tasks.
• Variable Management: List, get details, create, and delete variables with filtering, pagination, and namespace support.
• Volume Management: List, get details, delete volumes, and manage volume claims.
• ACL Management: Manage ACL tokens, policies, and roles, including creation, deletion, and bootstrapping the ACL system.
• Sentinel Policy Management: List, get details, create, and delete Sentinel policies.
• Cluster Management: Get cluster leader, list cluster peers, and list regions.

Use Cases of mcp-nomad

• Automated Nomad Cluster Operations: Programmatically control and automate tasks like job deployment, scaling, and monitoring.
• Integration with AI Agents (Claude): Utilize mcp-nomad with AI agents like Claude for intelligent management of Nomad resources.
• Custom Nomad Management Tools: Develop custom applications and scripts that interact with Nomad through the MCP.
• Observability and Monitoring: Browse and inspect Nomad cluster state using tools like Inspector.
• CI/CD Pipelines: Integrate Nomad operations into continuous integration and continuous delivery workflows.

FAQ about mcp-nomad

• What is MCP? MCP stands for Model Context Protocol, which is a protocol for interacting with models and services.
• What are the prerequisites for running mcp-nomad? Depending on the installation method, prerequisites can include Node.js, Golang, or Docker.
• How do I configure mcp-nomad to connect to my Nomad cluster? You can configure the Nomad server address using the -nomad-addr option or the NOMAD_ADDR environment variable. An optional NOMAD_TOKEN can be used for ACL authentication.
• Can I use mcp-nomad with Docker on macOS/Windows? Yes, specific Docker commands and Claude configurations are provided for macOS/Windows, requiring NOMAD_ADDR to be set to http://host.docker.internal:4646.
• What license is mcp-nomad released under? mcp-nomad is licensed under the MIT License.

Features

• List jobs
• Get job details
• Run jobs
• Stop jobs
• Get job versions
• Get job submission
• List job allocations
• List job evaluations
• List job deployments
• Get job deployment
• Get job summary
• Update jobs
• Dispatch parameterized jobs
• Revert jobs
• Set job stability
• Create job evaluations
• Create job plans
• Force new periodic instances
• Get job scale status
• Scale task groups
• List job services

• List deployments
• Get deployment details

• List namespaces
• Create namespaces
• Delete namespaces

• List nodes
• Get node details
• Drain nodes
• Set node eligibility

• List allocations
• Get allocation details
• Get allocation logs
• Get task logs

• List variables with filtering and pagination
• Get variable details
• Create variables with namespace support
• Delete variables with CAS support

Example variable operations:

# List variables in a namespace
list_variables namespace="my-namespace" prefix="my/path" per_page=10

# Get a specific variable
get_variable path="my/path" namespace="my-namespace"

# Create a variable
create_variable path="my/path" key="username" value="john" namespace="my-namespace"

# Delete a variable
delete_variable path="my/path" namespace="my-namespace"

• List volumes
• Get volume details
• Delete volumes
• List volume claims
• Delete volume claims

• List ACL tokens
• Get ACL token details
• Create ACL tokens
• Delete ACL tokens
• List ACL policies
• Get ACL policy details
• Create ACL policies
• Delete ACL policies
• List ACL roles
• Get ACL role details
• Create ACL roles
• Delete ACL roles
• Bootstrap ACL system

• List Sentinel policies
• Get Sentinel policy details
• Create Sentinel policies
• Delete Sentinel policies

• Get cluster leader
• List cluster peers
• List regions

Browse With Inspector

To use the latest published version with Inspector:

npx @modelcontextprotocol/inspector npx @kocierik/mcp-nomad

Options Available

  -nomad-addr string
    	Nomad server address (default "http://localhost:4646")
  -port string
    	Port for SSE server (default "8080")
  -transport string
    	Transport type (stdio or sse) (default "stdio")

Environment Variables

• NOMAD_ADDR: Nomad HTTP API address (default: http://localhost:4646)
• NOMAD_TOKEN: Nomad ACL token (optional)

Use With Claude

https://github.com/user-attachments/assets/731621d7-0acf-4045-bacc-7b34a7d83648

Installation Options

	Smithery	mcp-get	Pre-built NPM	Pre-built in Github	From sources	Using Docker
Claude Setup	Auto	Auto	Manual	Manual	Manual	Manual
Prerequisite	Node.js	Node.js	Node.js	None	Golang	Docker

Using Smithery

npx -y @smithery/cli install @kocierik/mcp-nomad --client claude

Using mcp-get

npx @michaellatman/mcp-get@latest install @kocierik/mcp-nomad

Prebuilt from npm

npm install -g @kocierik/mcp-nomad

Update your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp_nomad": {
      "command": "mcp-nomad",
      "args": [],
      "env": {
        "NOMAD_TOKEN": "${NOMAD_TOKEN}",
        "NOMAD_ADDR": "${NOMAD_ADDR}"
      }
    }
  }
}

From GitHub Releases

Download the binary and configure Claude Desktop like so:

{
  "mcpServers": {
    "mcp_nomad": {
      "command": "mcp-nomad",
      "args": [],
      "env": {
        "NOMAD_TOKEN": "${NOMAD_TOKEN}",
        "NOMAD_ADDR": "${NOMAD_ADDR}"
      }
    }
  }
}

Building from Source

go get github.com/kocierik/mcp-nomad
go install github.com/kocierik/mcp-nomad

Using Docker linux

docker run -i --rm --network=host kocierik/mcpnomad-server:latest

Using Docker macos/windows

docker run -i --rm \
  -e NOMAD_ADDR=http://host.docker.internal:4646 \
  kocierik/mcpnomad-server:latest

For Claude macos/windows:

{
  "mcpServers": {
    "mcp_nomad": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "NOMAD_TOKEN=secret-token-acl-optional", 
        "-e", "NOMAD_ADDR=http://host.docker.internal:4646",
        "mcpnomad/server:latest"
      ]
    }
  }
}

For Claude linux:

{
  "mcpServers": {
    "mcp_nomad": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NOMAD_ADDR=http://172.17.0.1:4646",
        "-e", "NOMAD_TOKEN=secret-token-acl-optional", 
        "kocierik/mcpnomad-server:latest"
      ]
    }
  }
}

License

This project is licensed under the MIT License - see the LICENSE file for details.