netmon-mcpd

# Netmon MCP

Connect an AI assistant to a Netmon appliance.

Netmon ships an MCP server on the appliance itself. This repository holds the client-side bridge: a small Node process that runs on your own machine, speaks stdio to Claude Desktop, and forwards every JSON-RPC message to your Netmon's `/mcp` endpoint over HTTPS.

Once connected, an assistant can read your devices, interfaces, logs, flow records, alerts, and Windows-agent data by calling Netmon's tools directly — with the same sign-in and permissions as any operator, and the same tag restrictions.

- **Product overview:** <https://netmon.com/netmon-ai-assistants/>
- **Setup guide:** <https://netmon.com/netmon-7-user-guide/api-and-integrations/>
- **API reference:** <https://netmon.com/api-reference/authentication/>

---

## Try it first — no appliance needed

A public, read-only demo server answers the same 36 tools from a recorded,
de-identified snapshot of a fictional 90-device network:

```
https://netmon.com/mcp-demo/mcp
```

No account, no token, no install. Point any MCP client at it — in Claude Code:

```bash
claude mcp add --transport http netmon-demo https://netmon.com/mcp-demo/mcp
```

or in a client config:

```json
{
  "mcpServers": {
    "netmon-demo": { "url": "https://netmon.com/mcp-demo/mcp" }
  }
}
```

Then ask it something real: *"what's down?"*, *"show me the Suricata alerts from
last week"*, *"which host is using the most bandwidth, and who is it talking to?"*

It is a fixture, not an appliance: nothing writes, nothing reaches a real network,
and every answer is the same shape a live Netmon returns — with timestamps shifted
forward so the snapshot always reads as the last day or so.

---

## Why a local bridge

Claude connects to remote MCP servers from Anthropic's cloud infrastructure, not from your machine. A Netmon appliance on a private network is not reachable from there.

The bridge runs as a local process, so it can reach the appliance on your LAN. That is the whole reason this repository exists — and it means the supported clients are **Claude Desktop** and **Claude Code**, not claude.ai in a browser.

If your appliance is internet-facing with a publicly-trusted certificate, you can skip the bridge and point any MCP client straight at the endpoint. See [Install — any MCP client](#install--any-mcp-client) below.

---

## Requirements

- A Netmon appliance with the MCP server enabled (Netmon 7.0.20 or newer).
- A user account with the **API** permission, and a personal access token carrying the `mcp:*` scopes you want the assistant to have.
- Claude Desktop for the `.mcpb` install. Claude Desktop supplies its own Node runtime, so nothing else is needed. Running the bridge outside Claude Desktop requires Node 18 or newer.

---

## Install — Claude Desktop

1. Download `netmon-mcp-<version>.mcpb` from [Releases](https://github.com/Netmon-Services/netmon-mcpd/releases). The same bundle ships with your appliance — **Settings → System → Downloadables → Claude Desktop Extension**.
2. In Claude Desktop, open **Settings → Extensions → Advanced settings → Extension Developer → Install Extension…** and select the file.
3. Fill in the two settings the extension asks for:

   | Setting | Value |
   |---|---|
   | **Netmon URL** | `https://<your-netmon>/mcp` — the full endpoint, including `/mcp` |
   | **API Token** | a personal access token (see below). The `Bearer ` prefix is added for you if you leave it off. |

4. Restart the extension. Ask Claude something like *"list the devices that are down"* to confirm it is working.

### Minting a token

In Netmon, go to **Settings → Users**, click the key icon on your user, and create a personal access token. Select only the scopes the assistant needs — the token cannot be widened later, and it can be revoked from the same screen at any time.

The account must hold the **API** permission. Without it, token minting and OAuth consent are both refused.

---

## Install — any MCP client

The appliance serves Streamable HTTP at `https://<your-netmon>/mcp` (`POST` for JSON-RPC, `GET` for the server-to-client SSE stream, `DELETE` to end a session).

Clients that support OAuth 2.1 discover the authorization server on their own: the endpoint answers an unauthenticated request with `401` and a `WWW-Authenticate: Bearer resource_metadata="…"` challenge pointing at RFC 9728 protected-resource metadata, alongside RFC 8414 authorization-server metadata and dynamic client registration at `/auth/register`. You sign in through your browser on your own Netmon and approve the scopes on a consent page.

Clients without OAuth support pass a token directly:

```json
{
  "mcpServers": {
    "netmon": {
      "url": "https://netmon.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}
```

### Claude Code and self-signed certificates

Most appliances serve a self-signed certificate. A direct `type: http` entry will fail against one — the OAuth bootstrap rejects the certificate and does not consult `NODE_EXTRA_CA_CERTS`. Use the bridge instead, which handles the certificate itself:

```json
{
  "mcpServers": {
    "netmon": {
      "command": "node",
      "args": ["/path/to/netmon-mcpd/server/index.js"],
      "env": {
        "NETMON_URL": "https://netmon.example.com/mcp",
        "NETMON_TOKEN": "<your-token>"
      }
    }
  }
}
```

---

## Tools

36 read tools, each wrapping a Netmon API endpoint and gated by an OAuth scope that is checked before the call runs.

| Area | Scope | Example tools |
|---|---|---|
| Devices & fleet | `mcp:devices` | `device_find`, `device_get`, `device_list`, `device_metric_summary`, `overwatch_summary`, `tags_list` |
| Traffic & topology | `mcp:vne`, `mcp:devices` | `top_bandwidth`, `netflow_search`, `netflow_raw_search`, `flow_summary`, `get_network_entity_info`, `arp_table`, `interfaces_search` |
| Logs & security | `mcp:logs` | `syslog_search`, `eventlog_search`, `eve_search`, `eve_get`, `log_severity_summary`, `syslog_facets` |
| Alerts | `mcp:alerts` | `alerts_list`, `alerts_history`, `maintenance_windows_list` |
| Windows agent | `mcp:devices` | `agent_processes`, `agent_services`, `agent_disk_usage` |
| Live tools | `mcp:tools`, `mcp:devices`, `mcp:capture` | `ping`, `traceroute`, `arp_lookup`, `port_map`, `snmp_test`, `snmp_walk_run`, `snmp_walk_last`, `search_ip`, `speedtest_history`, `capture_list`, `capture_get` |

<details>
<summary>All 36 tools</summary>

| Tool | Title | What it answers |
|---|---|---|
| `get_network_entity_info` | Look Up WHOIS, GeoIP and DNS | Retrieves WHOIS, GeoIP and DNS information for a public IP address or hostname. |
| `arp_lookup` | ARP Lookup | Performs an ARP lookup to find the MAC address for a given Local IP address. |
| `ping` | Ping Host | Ping a target host from the Netmon server. |
| `traceroute` | Run Traceroute | Traceroute to a target from the Netmon server. |
| `port_map` | Scan Open Ports | Nmap port scan against a single host from the Netmon server. |
| `search_ip` | Search All Streams for an IP | Find every mention of a specific IP across Netmon's log and telemetry streams: syslog, Windows eventlog, Suricata EVE, aggregated NetFlow, and ARP. |
| `syslog_search` | Search Syslog | Search syslog messages from network devices. |
| `eventlog_search` | Search Windows Event Log | Search Windows Event Log entries ingested from Netmon agents. |
| `eve_search` | Search Suricata IDS Events | Search Suricata EVE-format IDS events. |
| `eve_get` | Get Suricata IDS Event | Fetch a single Suricata EVE event by id, decoded server-side. |
| `log_severity_summary` | Summarize Log Severities | Count log events grouped by severity over a time window. |
| `syslog_facets` | Syslog Facet Breakdown | Top-N value counts for ONE syslog field over a window — 'what are the top actions/reasons on this FortiGate in the last 2 hours' in a single call,... |
| `netflow_search` | Search Aggregated NetFlow | Search the FULL NetFlow history: the raw flow table (the last ~15 minutes) unioned with the aggregated rollup (4 weeks of history), windowed and pr... |
| `netflow_raw_search` | Search Raw NetFlow | Search raw NetFlow records (per-flow, not aggregated). |
| `flow_summary` | Summarize NetFlow Traffic | Summarize one host's network conversations: top peers, top ports, and a client-vs-service-side split, each with a residual "other" bucket plus over... |
| `device_list` | List Devices | List monitored devices. |
| `device_get` | Get Device Details | Fetch one device with its related state: tags, alerts, the ping / oid / interface / port / disk trackers configured on it, its SNMP walk trackers,... |
| `device_find` | Find Devices by Name or IP | Find devices matching a substring of label or ip_address. |
| `overwatch_summary` | Overwatch Health Summary | High-level network health snapshot for 'how's the network?' style questions. |
| `snmp_test` | Test SNMP Credentials | Probe a device for SNMP reachability using the Netmon snmptest binary. |
| `snmp_walk_last` | Get Cached SNMP Walk | Fetch the most recent stored SNMP walk for a device (cached in tools_walks). |
| `snmp_walk_run` | Run Fresh SNMP Walk | Trigger a FRESH SNMP walk against a device. |
| `agent_services` | List Windows Services | List Windows services on an agent-managed device — live read via the WMI tunnel. |
| `agent_processes` | List Windows Processes | List running processes on an agent-managed device — live read via the agent tunnel. |
| `alerts_list` | List Alert Definitions | List configured alert definitions across both axes of the rule engine. |
| `alerts_history` | Alert Incident History | Authoritative 'what fired and when' stream — wraps the `alert_history` table (one row per incident, both legacy and modern) and `alert_outlet_log`... |
| `maintenance_windows_list` | List Maintenance Windows | Lists maintenance windows — the suppression schedules that gate alert dispatch. |
| `tags_list` | List Tags | List tag definitions. |
| `top_ban