Golang-based MCP server connecting to Nomad

MCP Nomad Go

Use with Claude ⚙ Server options ⚙ MCP Inspector (testing) ⚙ Contributing ↗ ⚙ About MCP ↗

Use With Claude

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

Installation Options

Prebuilt from npm

The package publishes a mcp-nomad CLI. Easiest zero-install option (downloads to npm’s cache; needs Node/npm):

npx -y @kocierik/mcp-nomad

Or install globally so mcp-nomad is on your PATH:

npm install -g @kocierik/mcp-nomad

claude_desktop_config.json with npx (recommended):

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

If you used npm install -g, keep command / args as the binary directly:

{
  "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

Server options

Command-line flags (also relevant when pairing with MCP Inspector against a manually started binary):

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

Environment variables

• NOMAD_ADDR: Nomad HTTP API address (default: http://localhost:4646)
• NOMAD_TOKEN: Nomad ACL token (optional)
• NOMAD_REGION: forwarded as the REST region query parameter when callers do not override it (multi-region clusters)
• NOMAD_NAMESPACE: default namespace for tools that accept an optional namespace when the tool omits it
• TLS: NOMAD_CACERT, NOMAD_SKIP_VERIFY, NOMAD_TLS_SERVER_NAME (see utils/client.go / buildTLSConfig)

The HTTP client follows the official /v1/ API and is split across utils/client_*.go; MCP tools depend on narrow interfaces in utils/nomad_tool_interfaces.go.

NomadClient.MakeRequest (used only for a few cluster/legacy call sites) rejects paths outside an internal allow-list — prefer typed helpers such as StopAllocation.

Browse with MCP Inspector

Use this for local testing and debugging — not required for Claude Desktop daily use.

To run the latest published npm build under the MCP Inspector:

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

Inspector with a local HTTP server (optional)

Default transport is stdio. To attach the Inspector as Streamable HTTP, start the binary in another terminal first:

go run . -transport=streamable-http -port=8080

Then open http://localhost:8080/mcp in the Inspector. For -transport=sse, use http://localhost:8080/sse.

License

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