Mcp Nomad Go

What is Mcp Nomad Go about?

Mcp Nomad Go implements an MCP server written in Go that connects to a Nomad cluster. It translates Nomad's HTTP API into Model Context Protocol calls, enabling clients—such as Claude Desktop or other MCP‑compatible tools—to manage Nomad resources programmatically.

How to use Mcp Nomad Go?

1. Install the server via npm (or use the pre‑built binary/Docker image). The most convenient method is:

   npx -y @kocierik/mcp-nomad
   

2. Configure environment variables (or command‑line flags) to point the server at your Nomad instance:
   • NOMAD_ADDR – Nomad HTTP API address (default http://localhost:4646).
   • NOMAD_TOKEN – Optional ACL token.
3. Run the server. By default it starts an SSE server on port 8080 and uses the stdio transport unless overridden.
4. Connect your MCP client (e.g., Claude Desktop) by adding the server definition to claude_desktop_config.json as shown in the README.

Key features of Mcp Nomad Go

• Job Management: list, create, update, run, stop, scale, dispatch parameterized jobs, retrieve versions, logs, and summaries.
• Deployment Management: list and inspect deployments.
• Namespace Management: create, list, and delete namespaces.
• Node Management: list nodes, get details, drain, and set eligibility.
• Allocation Management: list allocations, fetch allocation and task logs.
• Variable Management: CRUD operations with namespace support and CAS delete.
• Volume Management: list, inspect, and delete volumes and claims.
• ACL Management: full lifecycle for tokens, policies, and roles, plus ACL bootstrap.
• Sentinel Policy Management: list, get, create, and delete Sentinel policies.
• Cluster Management: retrieve leader, peers, and region information.
• Transport Options: stdio (default) or sse (Server‑Sent Events).

Use cases of Mcp Nomad Go

• Automation pipelines: integrate Nomad job orchestration into AI‑driven workflows via MCP.
• Chat‑ops: enable conversational agents (e.g., Claude) to execute Nomad tasks on demand.
• Monitoring dashboards: expose Nomad state through MCP for real‑time UI components.
• Multi‑environment management: manage jobs across different namespaces and regions from a single MCP endpoint.
• CI/CD integration: trigger job runs and deployments from code repositories using MCP calls.

FAQ from the Mcp Nomad Go

Q: Which transport should I choose?

• stdio is ideal for local CLI usage. sse is recommended when the server must push events to remote clients.

Q: How do I expose the server over the network?

• Ensure the -port flag is set to a reachable port (default 8080) and that your firewall allows inbound traffic.

Q: Can I run the server in Docker?

• Yes. Use the official image:

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

  Adjust NOMAD_ADDR and NOMAD_TOKEN via -e flags as needed.

Q: Do I need a Nomad ACL token?

• Only if your Nomad cluster enforces ACLs. Provide it via NOMAD_TOKEN.

Q: How are releases managed?

• Binary releases are published on GitHub; the latest version can be installed with the npx command above.

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.