kocierik/mcp-nomad

Developer tools

59 stars 17 forks Quality 85 Trend 33MIT

Repository Install

Golang-based MCP server connecting to Nomad

Overview

Golang-based MCP server connecting to Nomad

README

Golang-based MCP server connecting to Nomad

MCP Nomad Go

Quick start ⚙ Tools ⚙ Configuration ⚙ HTTP mode ⚙ Development ↗ ⚙ About MCP ↗

mcp-nomad lets AI assistants such as Claude inspect and operate a HashiCorp Nomad cluster: jobs, allocations, logs, nodes, variables, ACLs and more.

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

Quick start

Add the server to claude_desktop_config.json (requires Node.js):

{
  "mcpServers": {
    "mcp_nomad": {
      "command": "npx",
      "args": ["-y", "@kocierik/mcp-nomad"],
      "env": {
        "NOMAD_ADDR": "http://127.0.0.1:4646",
        "NOMAD_TOKEN": ""
      }
    }
  }
}

Add "-read-only" to args to expose only tools that cannot change the cluster.

Other ways to install; then use "command": "mcp-nomad" with the same env:

npm: npm install -g @kocierik/mcp-nomad
Binary: download from GitHub Releases
Source: go install github.com/kocierik/mcp-nomad@latest

Available tools

Area	Read	Write
Jobs	`list_jobs`, `get_job`, `get_job_summary`, `get_job_allocations`, `get_job_evaluations`, `get_evaluation`, `get_job_deployments`, `get_job_services`	`run_job`, `stop_job`, `scale_job`
Deployments	`list_deployments`, `get_deployment`
Allocations	`list_allocations`, `get_allocation`, `get_allocation_logs`	`stop_allocation`
Nodes	`list_nodes`, `get_node`	`drain_node`, `eligibility_node`
Namespaces	`list_namespaces`	`create_namespace`, `delete_namespace`
Variables	`list_variables`, `get_variable`	`create_variable`, `delete_variable`
Volumes	`list_volumes`, `get_volume`	`delete_volume`
ACL	`list_acl_tokens`, `get_acl_token`, `list_acl_policies`, `get_acl_policy`, `list_acl_roles`, `get_acl_role`	`create_acl_token`, `delete_acl_token`, `create_acl_policy`, `delete_acl_policy`, `create_acl_role`, `delete_acl_role`, `bootstrap_acl_token`
Sentinel	`list_sentinel_policies`, `get_sentinel_policy`	`create_sentinel_policy`, `delete_sentinel_policy`
Cluster	`get_cluster_leader`, `list_cluster_peers`, `list_regions`

With -read-only the write column is not available at all. Whatever the mode, the Nomad ACLs attached to NOMAD_TOKEN decide what is actually allowed: use a token with only the permissions you want the assistant to have.

The server also provides resources (job specs and history, node status, allocation status and logs) and prompts.

Configuration

Variable	Purpose
`NOMAD_ADDR`	Nomad API address (default `http://127.0.0.1:4646`)
`NOMAD_TOKEN`	Nomad ACL token
`NOMAD_NAMESPACE`	Default namespace when a request does not specify one
`NOMAD_REGION`	Default region for multi-region clusters
`NOMAD_CACERT`, `NOMAD_TLS_SERVER_NAME`, `NOMAD_SKIP_VERIFY`	TLS to Nomad
`NOMAD_CLIENT_CERT`, `NOMAD_CLIENT_KEY`	Mutual TLS to Nomad

Flag	Default	Purpose
`-transport`	`stdio`	`stdio`, `sse` or `streamable-http`
`-read-only`	off	Only register tools that cannot change the cluster
`-port`	`8080`	HTTP port
`-listen-address`	`127.0.0.1`	HTTP listen address

HTTP mode (optional)

Claude Desktop uses stdio and needs nothing from this section.

The sse and streamable-http transports are protected by a bearer token, separate from the Nomad token:

export MCP_TOKEN=""
mcp-nomad -transport=streamable-http

Every request must send Authorization: Bearer ; the server refuses to start without it.
The server listens on 127.0.0.1 only. Use -listen-address=0.0.0.0 (for example in Docker) only behind a trusted network or HTTPS reverse proxy.
Browser clients from other origins must be listed in MCP_ALLOWED_ORIGINS (comma-separated, e.g. http://localhost:6274).

Details: SECURITY.md.

Upgrading from 0.3.x: HTTP transports now require MCP_TOKEN and listen on 127.0.0.1 by default.

Testing with MCP Inspector

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

To test HTTP mode, start the server as shown above with MCP_ALLOWED_ORIGINS="http://localhost:6274", open http://localhost:8080/mcp in the Inspector and enter MCP_TOKEN as the bearer token.

License

MIT, see LICENSE.

View the full README on GitHub

Install

npx -y @kocierik/mcp-nomad

New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "mcp_nomad": {
      "command": "npx",
      "args": ["-y", "@kocierik/mcp-nomad"],
      "env": {
        "NOMAD_ADDR": "http://127.0.0.1:4646",
        "NOMAD_TOKEN": "<your-nomad-acl-token>"
      }
    }
  }
}