AI-Powered Network Monitoring: Introducing ntopng MCP Server

May 21, 2026

AI-Powered Network Monitoring: Introducing ntopng MCP Server for Headless Security

Connect your network monitoring directly to AI assistants. Query ClickHouse flows, pull live host stats, and automate security investigations—all through natural language.

What is MCP?
Why Headless Network Security?
Generate Your API Token
Add ntopng to Claude Code
Available Tools
Use Cases: SOC Analysts
Use Cases: Network Managers
Security Best Practices
Troubleshooting
FAQ

What is MCP?

The Model Context Protocol (MCP) exposes ntopng’s network data and tools to AI assistants like Claude Code, Cursor, and VS Code extensions. Instead of manually querying dashboards or writing SQL, you describe what you need in plain language.

MCP allows you to:

Run ClickHouse SQL queries on 24 months of flow data.
Get real-time stats on active hosts and flows.
Query SNMP device inventory and interface details.
Search ntopng documentation inline.
Set up active monitoring with natural language.
Create security policies on demand.

Contrary to most tools that are monolithic and thus run an MCP server as an external process, ntopng MCP server is implemented inside ntopng preventing you to install and run an additional component.

Above you can see an example of how the ntopng MCP server works. The only requirement on your side is to update ntopng to the latest dev version (table version will include it soon),

Why Headless Network Security?

Headless security means monitoring infrastructure through APIs and automation—no dashboard access required. SOC teams and network managers benefit from:

Speed
Ask a question, get context and recommendations in seconds instead of minutes of manual investigation.
Completeness
Single conversation pulls data from multiple sources: live flows, historical queries, device inventory, alert configurations.
Automation
Set monitoring thresholds, build policies, and enable checks without CLI commands or manual configuration.

Generate Your API Token

Step 1: Access Settings

In ntopng UI, go to the Settings -> Users -> User Authentication Token -> Generate Token

Step 2: Copy the Token

Add ntopng to Claude Code

claude mcp add-json ntopng \
  '{"type":"http","url":"http://NTOPNG_URL:NTOPNG_PORT/lua/rest/v2/exec/llm/mcp.lua","headers":{"Authorization":"Token YOUR_TOKEN"}}' \
  --scope user

Replace:

NTOPNG_URL: hostname or IP (localhost, monitor.company.com)
NTOPNG_PORT: ntopng port (default 3000)
YOUR_TOKEN: paste your token from Step 3

Example:

claude mcp add-json ntopng \
  '{"type":"http","url":"http://localhost:3000/lua/rest/v2/exec/llm/mcp.lua","headers":{"Authorization":"Token ntop_abc123def456"}}' \
  --scope user

Verification

Run the claude mcp add-json
Restart Claude Code
Type /mcp and you should see the ntopng MCP as in the image below.
Check in the available tools if tools and connection are correctly initialized

Available Tools

The list of tools available to the LLM via the ntopng embedded MCP server depends on the ntopng edition you are using. As of today there list of the available tools is listed below but we envisage users to contribute and create new ones:

Tools are written in Lua using the ntopng APIs.
Installation is simple as you just need to drop them into the LLM folder. See this page as reference for the available tools.

Community Edition (9 Tools)

Free and open source. Available in all ntopng installations.

Tool	Purpose
add_active_monitoring_script	Enable a new active monitoring script for a host
get_country_stats	Return top-N countries ranked by traffic seen on the current interface
get_host_info	Retrieve live, in-memory traffic statistics for a host that is currently active on the network
get_live_flows_for_host	Return active (live) flows involving a specific IP address on the current interface
get_live_flows_summary	Return an aggregated summary of active flows on the current interface
get_mac_info	Return details for a given MAC address: manufacturer, device type, host pool
list_available_active_monitoring_scripts	Retrieve all available active monitoring script definitions
list_enabled_active_monitoring_scripts	Retrieve all currently enabled active monitoring scripts
list_expected_servers	Return the IP addresses of all EXPECTED/APPROVED network infrastructure servers (DNS, NTP, DHCP, SMTP, gateways)

Enterprise Edition (20+ Tools)

Includes all community tools plus new tools that interact with Clickhouse Database, with Wazuh Server and many more functions to enable agentic usage!

Use Cases: SOC Analysts

Case 1: Investigate Suspicious DNS Queries

Scenario: Your SIEM flagged unusual DNS queries to known malware C2 domains.

Analyst: “Which hosts queried malicious-domain.com in the last 24 hours?”

Claude:

Calls query → ClickHouse: SELECT src_ip, count() FROM flows WHERE L7_PROTO='dns' AND DOMAIN_NAME LIKE '%malicious%' AND FIRST_SEEN >= now() - INTERVAL 1 day GROUP BY src_ip
Returns: “192.168.1.42 queried 23 times, 10.0.0.5 queried 3 times”
Analyst checks: “Get live stats on 192.168.1.42”
Claude: get_host_info -> Shows active server ports, recent flows, alert history
Result: Analyst has full context to decide: block host, isolate, or monitor

Time to decision: sub 1 minutes (vs. 10-15 min of manual investigation)

Case 2: Detect Data Exfiltration

Scenario: Large data transfer to external IP during off-hours.

Analyst: “Show me the top 5 outbound flows to non-local IPs in the last hour by bytes transferred”

Claude:

Calls query -> SELECT src_ip, dst_ip, dst_port, SUM(bytes) FROM flows WHERE dst_ip NOT IN (192.168.0.0/16, ...) AND FIRST_SEEN >= now() - INTERVAL 1 hour GROUP BY src_ip, dst_ip ORDER BY SUM(bytes) DESC LIMIT 5
Returns: 10.0.0.8 → 203.0.113.50:443 = 500 MB (suspicious)
Analyst: “What’s the protocol and domain for that flow?”
Claude: “HTTPS to known CDN (Akamai). Likely legitimate unless that host shouldn’t access external”
Analyst: “Add alert exclusion for that host-domain pair”
Claude: Calls add_domain_alert_exclusion → Suppresses future alerts for that flow

Outcome: Differentiate data exfil from legitimate cloud access in 3 minutes

Case 3: Track Botnet Command & Control

Scenario: Multiple hosts contacting same external IP on non-standard port.

Analyst: “Find all hosts contacting 45.142.222.50:8443 in the last 7 days”

Claude:

Calls query → SELECT DISTINCT src_ip, dst_ip, dst_port, COUNT() as flow_count, SUM(bytes) FROM flows WHERE dst_ip='45.142.222.50' AND dst_port=8443 AND FIRST_SEEN >= now() - INTERVAL 7 day GROUP BY src_ip
Returns: 12 hosts found (192.168.1.x, 10.0.0.x ranges)
Analyst: “Get asset info on each host”
Claude: For each IP → OS, device model, first/last seen, network segment
Analyst: Correlates with alerting system → Confirms C2 beaconing
Decides: Quarantine all 12 hosts, capture PCAP for forensics

Outcome: Lateral movement detection and containment in 5 minutes

Use Cases: Network Managers

Case 1: Identify Bandwidth Hogs

Scenario: Interface utilization at 80%. Need to find culprits.

Manager: “Show me the top 10 conversations consuming bandwidth on eth0 in the last 6 hours”

Claude:

Calls query → SELECT src_ip, dst_ip, L7_PROTO, SUM(bytes) FROM flows WHERE src_port != 0 AND FIRST_SEEN >= now() - INTERVAL 6 hour GROUP BY src_ip, dst_ip, L7_PROTO ORDER BY SUM(bytes) DESC LIMIT 10
Returns table: Server-to-Server (HTTP/S), Backup Traffic (SMB), Video Streaming (QUIC)
Manager: “Which of these are scheduled vs. anomalous?”
Claude: Suggests normal patterns (backup 2–4 AM, traffic during business hours)
Manager: Decides to upgrade backup schedule, monitor video traffic

Outcome: Data-driven capacity planning decision in 10 minutes

Case 2: Monitor VPN Concentrator Health

Scenario: Remote workers report slow VPN connections.

Manager: “Get SNMP stats on VPN-gateway-01 (192.168.255.1)”

Claude:

Calls get_snmp_device_info → Shows all interfaces, CPU 45%, Memory 78%, Link status
Manager: “Which interface has highest traffic?”
Claude: eth1 (WAN): 500 Mbps inbound, 200 Mbps outbound
Manager: “How many active VPN sessions connected right now?”
Claude: Calls query → SELECT COUNT(DISTINCT src_ip) FROM flows WHERE L4_PROTO='UDP' AND dst_port=1194
Result: 250 active sessions (expected max 200)
Manager: Triggers capacity alert, schedules gateway upgrade

Outcome: Identify bottleneck, justify capacity expansion in 5 minutes

Case 3: Verify Monitoring Coverage

Scenario: Need to confirm all critical devices are monitored.

Manager: “List all SNMP devices we’re monitoring”

Claude:

Calls list_snmp_devices → Returns 47 devices
Manager: “Which ones haven’t reported in the last hour?”
Claude: Identifies 3 unreachable devices
Manager: “Get asset info on those IPs”
Claude: Returns OS, model, last known config
Manager: Checks firewall rules, restarts those devices, confirms reachability

Outcome: Proactive monitoring gap discovery, 3-minute fix

Read vs. Write Tools

Read-only (safe to call): query, chart, describe_table, get_host_info, get_asset_info, list_snmp_devices, get_live_flows_for_host, get_live_flows_summary, search_docs

Write (requires confirmation): add_host_alert_exclusion, add_domain_alert_exclusion, add_certificate_alert_exclusion, add_active_monitoring_script, create_ai_policy. Claude will always ask before executing.

Troubleshooting

No tools available (ntopng pro LLM tools not available)

Cause: Running ntopng Community edition (Pro module missing).

Fix: Use free community tools (9 tools listed above). Or upgrade to Enterprise for full toolset.

ClickHouse queries fail (table not found)

Cause: ClickHouse export not enabled.

Empty response from get_host_info

Cause: Host aged out of in-memory cache.

Fix: Use query tool for historical data. Use get_asset_info for persistent device inventory.

FAQ

Is MCP free?

Yes. Community tools and MCP protocol are free. Pro/Enterprise customers access all 20 tools.

Can I use this with remote ntopng?

Yes. Provide full URL and ensure network connectivity. Use HTTPS for security.

What if I lose my token?

Generate a new one in Settings → Generate Token.

Can multiple users share one token?

Yes, but use separate tokens per user for audit trail accountability.

Does MCP work with Cursor or other clients?

Yes. MCP is a standard protocol. Configure the same HTTP endpoint in Cursor, VS Code, or custom Python agents.

What data does Claude see?

Only what tools return: flow query results (IPs, ports, bytes, protocols), host stats (CPU, memory, interface speeds), device inventory, alert configs. No raw packet data.

Enjoy and contribute to the MCP tools list !

AI-Powered Network Monitoring: Introducing ntopng MCP Server