opennms-mcp

An MCP (Model Context Protocol) server that connects Claude to OpenNMS. Ask Claude to list alarms, inspect nodes, send events, update asset records, manage categories, and control service collection — all in plain language.

Prerequisites

• Node.js 22+

• An OpenNMS instance reachable over HTTP/HTTPS

• A user account with API access (admin or a read/write role)

Related MCP server: openwebui-mcp-server

Installation

git clone https://github.com/c-perronnet/opennms-mcp.git
cd opennms-mcp
npm install
npm run build

Configuration

Create a JSON file with your OpenNMS credentials. Two auth formats are supported:

Basic auth (opennms/myserver.json):

{
  "url": "https://opennms.example.com",
  "username": "admin",
  "password": "secret"
}

Token auth (opennms/myserver.json):

{
  "url": "https://opennms.example.com",
  "token": "your-api-token"
}

Add "insecure": true to either format to skip TLS certificate validation (useful for self-signed certs).

Store config files in the opennms/ directory — it is git-ignored so credentials are never committed.

Connecting to Claude Desktop

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "opennms": {
      "command": "node",
      "args": ["/absolute/path/to/opennms-mcp/dist/index.js"],
      "env": {
        "OPENNMS_CONFIG": "/absolute/path/to/opennms-mcp/opennms/myserver.json"
      }
    }
  }
}

Alternatively, pass the config path as a positional argument:

{
  "mcpServers": {
    "opennms": {
      "command": "node",
      "args": [
        "/absolute/path/to/opennms-mcp/dist/index.js",
        "/absolute/path/to/opennms-mcp/opennms/myserver.json"
      ]
    }
  }
}

Connecting to Claude Code

Claude Code reads MCP server config from ~/.claude/claude_mcp_settings.json. Add the server there:

{
  "mcpServers": {
    "opennms": {
      "command": "node",
      "args": ["/absolute/path/to/opennms-mcp/dist/index.js"],
      "env": {
        "OPENNMS_CONFIG": "/absolute/path/to/opennms-mcp/opennms/myserver.json"
      }
    }
  }
}

Or configure it via the CLI:

claude mcp add opennms \
  -e OPENNMS_CONFIG=/absolute/path/to/opennms-mcp/opennms/myserver.json \
  -- node /absolute/path/to/opennms-mcp/dist/index.js

Verify the server is loaded with /mcp in the Claude Code prompt. The tools listed below will then be available in any conversation.

Available tools

Connectivity

Alarms

Nodes

Events

Asset records

Categories

Collection / polling

FIQL filtering

Several list tools accept a filter parameter using FIQL syntax:

Examples:

• severity==CRITICAL — critical alarms only

• node.label==web* — nodes whose label starts with "web"

• severity==MAJOR,severity==CRITICAL — major or critical alarms

• category.name==Routers — nodes in the Routers category

Development

npm run dev    # watch mode — recompiles on file changes
npm run build  # one-shot compile to dist/
npm start      # run compiled server (requires OPENNMS_CONFIG)

License

MIT