OpenNMS MCP

MCP server experiments for OpenNMS and network-management automation workflows. This server exposes OpenNMS alarms, nodes, events, assets, categories, and collection controls to MCP clients so operators can interrogate and act on NMS state through a controlled tool interface.

Current Signal

Area	Status
Runtime	Node.js 22+ / TypeScript
Protocol	Model Context Protocol (MCP)
Network system	OpenNMS REST/event APIs
Active tools	Alarms, nodes, events, assets, categories, service collection
Automation posture	npm audit plus build CI
Next enrichment	Integration tests with mocked OpenNMS responses

The Unfair Advantage

OpenNMS already knows the network. This project turns that knowledge into an assistant-accessible control plane: list critical alarms, inspect nodes, send events, update asset records, manage categories, and control service collection without burying operators in click paths.

Prerequisites

• Node.js 22+
• An OpenNMS instance reachable over HTTP/HTTPS
• An OpenNMS user account with API access

Installation

git clone https://github.com/Lipford-Dutch/opennms-mcp.git
cd opennms-mcp
npm ci
npm run build

Configuration

Create a JSON file with your OpenNMS credentials. Keep it outside Git history. The recommended local path is opennms/myserver.json.

Basic auth:

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

Token auth:

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

Add "insecure": true only for lab systems with self-signed certificates. Production deployments should validate TLS.

Claude Desktop

Add the server to 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"
      ]
    }
  }
}

Claude Code

Claude Code reads MCP server config from ~/.claude/claude_mcp_settings.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"
      }
    }
  }
}

Or configure it via 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.

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 by 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 IP interface.
enable_service_collection	Enable collection for a service.
disable_service_collection	Disable collection for a service.

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 for critical alarms only.
• node.label==web* for nodes whose label starts with web.
• severity==MAJOR,severity==CRITICAL for major or critical alarms.
• category.name==Routers for nodes in the Routers category.

Development

npm ci
npm run build
npm start

npm start requires OPENNMS_CONFIG or a positional config path.

Active Discussions

• Kickoff: next 30-day field plan
• Bot scan review: findings, false positives, and fixes

License

MIT