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)

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

Tool	Description
server_info	Verify connectivity and return OpenNMS version

Alarms

Tool	Description
list_alarms	List alarms, optionally filtered by FIQL expression
get_alarm	Get full details for an alarm by ID
acknowledge_alarm	Acknowledge an alarm
modify_alarm	Unacknowledge, clear, or escalate an alarm

Nodes

Tool	Description
list_nodes	List nodes, optionally filtered by FIQL expression
get_node	Get full node details (accepts numeric ID or foreignSource:foreignId)
get_node_ip_interfaces	List IP interfaces for a node
get_node_snmp_interfaces	List SNMP interfaces for a node
get_node_outages	List outages for a node
rescan_node	Trigger a capability rescan for a node

Events

Tool	Description
list_events	List events, optionally filtered by FIQL expression
get_event	Get full details for an event by ID
send_event	Send a custom event to the OpenNMS event bus

Asset records

Tool	Description
get_node_asset_record	Get the asset record for a node
update_node_asset_record	Update one or more asset fields for a node

Categories

Tool	Description
list_categories	List all categories defined in OpenNMS
get_node_categories	List categories assigned to a node
add_category_to_node	Assign a category to a node
remove_category_from_node	Remove a category from a node

Collection / polling

Tool	Description
list_node_services	List monitored services on a node's IP interface
enable_service_collection	Enable collection for a service (set to Active)
disable_service_collection	Disable collection for a service (set to Forced Unmanaged)

FIQL filtering

Several list tools accept a filter parameter using FIQL syntax:

Operator	Meaning
==	equals
!=	not equals
=lt=	less than
=gt=	greater than
;	AND
,	OR

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