NTOPNG

This MCP Server connects to ntopng data and lets AI agents query network monitoring information stored in ntopng’s ClickHouse backend. You can retrieve interface IDs, host locations, alert statistics, and detailed flows to power decision making, monitoring, and automated analysis.

How to use

You interact with this MCP Server through an MCP client. Use the available endpoints to fetch interface lists, host locations, alert statistics, and detailed flows from ntopng. Typical workflows include discovering interfaces, inspecting top talkers, and querying flow data for investigations or alerting workflows. The server is designed to expose structured data you can feed into your AI agents for monitoring, anomaly detection, and incident response.

How to install

Prerequisites you need before installation are Python and the MCP runtime environment (uv). Ensure you have a working Python environment and the uv runtime installed.

1. Install and prepare the MCP runtime if you have not already:

uv sync uv pip install -e .

2. Navigate to the development setup for the MCP server:

cd mcp_ntopng

3. Prepare your environment and run the MCP server with the provided configuration. Load environment variables from a file or set them in your shell, then start the server using the MCP runner command shown in the configuration snippet below. You can also use a .env file to supply the variables.

$ source .env $ CLIENT_PORT=8077 SERVER_PORT=8078 mcp dev run_mcp_ntopng.py --with clickhouse-driver --with python-dotenv --with uvicorn --with pip-system-certs

4. The runtime will initiate the MCP server that interfaces with ntopng and ClickHouse according to the environment settings. Ensure the ntopng host, port, user, and password are provided through the environment variables shown in the configuration snippet.

Configuration

Configure your MCP client to load the server by adding the following MCP server entry. This registers the ntopng MCP server with the runtime and provides the necessary environment variables that connect to ntopng and its ClickHouse database.

{
  "mcpServers": {
    "mcp-ntopng": {
      "command": "/path/to/your/uv-binary",
      "args": ["run", "--with", "mcp-ntopng", "--python", "3.13", "mcp-ntopng"],
      "env": {
        "NTOPNG_HOST": "<ntopng-host>",
        "NTOPNG_DBPORT": "<ntopng-dbport>",
        "NTOPNG_DBUSER": "<ntopng-dbuser>",
        "NTOPNG_DBPASSWORD": "<ntopng-dbpassword>",
        "NTOPNG_SECURE": "true",
        "NTOPNG_VERIFY": "true",
        "NTOPNG_CONNECT_TIMEOUT": "30",
        "NTOPNG_SEND_RECEIVE_TIMEOUT": "300",
        "NTOPNG_API_KEY": "NTOPNG_TOKEN"
      }
    }
  }
}

Additional notes

Environment variables control how the MCP server connects to ntopng and its ClickHouse datastore. The following are commonly used and should be configured in your environment or in the configuration file: NTOPNG_HOST, NTOPNG_DBPORT, NTOPNG_DBUSER, NTOPNG_DBPASSWORD, NTOPNG_API_KEY. Optional TLS related options (NTOPNG_SECURE and NTOPNG_VERIFY) govern secure connections and certificate verification.

Security and testing

When deploying, keep sensitive credentials (db passwords and API keys) in secure environment files or secret stores. Test connections in a controlled environment by validating that ntopng is reachable at the configured host and port, and that ntopng can query ClickHouse for historical flows and alerts.

Troubleshooting

If you encounter timeouts when connecting to ClickHouse, increase NTOPNG_CONNECT_TIMEOUT and NTOPNG_SEND_RECEIVE_TIMEOUT. Verify TLS settings if using NTOPNG_SECURE and NTOPNG_VERIFY and confirm that the API key is valid. Check that the ntopng host value is reachable from the machine running the MCP server.

Available tools

fetch_ntopng_all_ifids

Retrieve all available interface IDs from ntopng.

get_ntopng_hosts_location

Fetch geographical location and additional info for hosts.

fetch_ntopng_top_local_talkers

Retrieve the top 10 local talkers for a specified interface.

fetch_ntopng_top_remote_talkers

Retrieve the top 10 remote talkers for a specified interface.

get_ntopng_all_alert_stats

Retrieve statistics for all alerts.

get_ntopng_flow_alert_stats

Retrieve statistics for flow alerts.

get_ntopng_host_alert_stats

Retrieve statistics for host alerts.

get_ntopng_interface_alert_stats

Retrieve statistics for interface alerts.

get_ntopng_mac_alert_stats

Retrieve statistics for MAC alerts.

get_ntopng_network_alert_stats

Retrieve statistics for network alerts.

get_ntopng_snmp_device_alert_list

Retrieve a list of SNMP device alerts.

get_ntopng_snmp_device_alert_stats

Retrieve statistics for SNMP device alerts.

get_ntopng_system_alert_stats

Retrieve statistics for system alerts.

query_ntopng_flows_data

Retrieve detailed flows data from the ntopng flows database.

get_ntopng_top-k_flows

Retrieve top-k flows data from the ntopng flows database.

get_ntopng_user_alert_stats

Retrieve statistics for user alerts.

get_ntopng_flow_devices_stats

Retrieve statistics for all flow devices.

get_ntopng_sflow_devices_stats

Retrieve statistics for all sFlow devices.

list_tables_ntopng_database

List tables structure of the ntopng database.

query_ntopng_database

Query the ntopng ClickHouse database.