mcp-server-ntopng

NTOPNG Model Context Protocol Server

A Model Context Protocol server implementation for NTOPNG that enables AI agents to query networks monitoring data using the NTOPNG database.

This MCP Server assumes that ntopng is using ClickHouse to store historical flows and alert. Check ntopng Clickhouse

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 dev`ices.

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.

Status

Works with Claude Desktop app and other MCP compliant hosts and clients.

No support for MCP resources or prompts yet.

Configuration

Create or edit the Claude Desktop configuration file located at:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%/Claude/claude_desktop_config.json
Add the following:

{
  "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"
      }
    }
  }
}

Replace /path/to/your/uv-binary with the absolute path to the uv executable. Find the path with which uv. This ensures that the correct version of uv is used when starting the server.
Restart Claude Desktop to apply the changes.

Development

Set the environmental variables either in the claude_desktop_config.json file or in a .env file in the root of the repository.

NTOPNG_HOST=localhost
NTOPNG_PORT=9000
NTOPNG_USER=default
NTOPNG_PASSWORD=

Run uv sync to install the dependencies. To install uv follow the instructions here. Then do source .venv/bin/activate.
Install the mcp-ntopng package with uv pip install -e . from the project main directory.
For easy testing, you can run mcp dev mcp_ntopng/mcp_server.py to start the MCP server. CHANGE WITH A PROPER CHAT CLIENT

Environment Variables

The following environment variables are used to configure the database connection:

NTOPNG_HOST: The hostname of the ntopng server
NTOPNG_DBUSER: The username for Clickhouse DB authentication
NTOPNG_DBPASSWORD: The password for Clickhouse DB authentication
NTOPNG_API_KEY: The ntopng authentication token.

Optional

NTOPNG_DBPORT: The port number of the Clickhouse DB in the ntopng server
- Default: 9000 if HTTPS is enabled, 8123 if disabled
- Usually doesn't need to be set unless using a non-standard port
NTOPNG_SECURE: Enable/disable a TLS connection
- Default: false
- Set to true for a secure TLS connections
NTOPNG_VERIFY: Enable/disable SSL certificate verification
- Default: true
- Set to `false to disable certificate verification (not recommended for production)
NTOPNG_CONNECT_TIMEOUT: Connection timeout in seconds
- Default: `30
- Increase this value if you experience connection timeouts
NTOPNG_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds
- Default: 300
- Increase this value for long-running queries

Check TLS Setup in the ntopng documentation for details about setting up a TLS connection to Clickhouse.

Development

Install the package on the local machine:

$ uv sync
$ uv pip install -e .

Run the MCP Inspector

$ cd mcp_ntopng
$ 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

Use the local library in Claude Desktop.

Find: /Users/marco/Library/Application\ Support/Claude/claude_desktop_config.json

Edit the claude_desktop_config.json changing the local paths:

{
    "mcpServers": {
      "mcp-ntopng": {
        "command": "/Users/marco/Development/claude/mcp-server-ntopng/.venv/bin/python",
        "args": [
           "/Users/marco/Development/claude/mcp-server-ntopng/run_mcp_ntopng.py"
        ],
        "env": {
          "NTOPNG_HOST": "marcoeg-nod004.ntoplink.com",
          "NTOPNG_DBPORT": "9000",
          "NTOPNG_DBUSER": "default",
          "NTOPNG_DBPASSWORD": "",
          "NTOPNG_SECURE": "false",
          "NTOPNG_VERIFY": "false",
          "NTOPNG_CONNECT_TIMEOUT": "30",
          "NTOPNG_SEND_RECEIVE_TIMEOUT": "300",
          "SELECT_QUERY_TIMEOUT_SECS": "30",
          "NTOPNG_API_KEY": "NTOPNG_TOKEN"
        }
      }
    }
  }

mcp-ntopng

Integrations

mcp-server-ntopng

Tools

Status

Configuration

Development

Environment Variables

Optional

Development

Related Resources