playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

ntopng MCP server

Integrates with ntopng systems to provide direct access to network monitoring data through ClickHouse database queries and REST API endpoints for retrieving traffic statistics, analyzing flows, and identifying network anomalies.
Back to servers
Setup instructions
Provider
Marco Graziano
Release date
Mar 21, 2025
Language
Python
Package
pypi
Stats
1.3K downloads
View on GitHub

The NTOPNG Model Context Protocol (MCP) Server enables AI agents to query network monitoring data stored in NTOPNG's ClickHouse database. This server implementation bridges the gap between AI systems and network monitoring, allowing natural language queries about network traffic, alerts, and device statistics.

Installation

You can install the MCP NTOPNG server using pip:

pip install mcp-ntopng

For the most recent version, we recommend using uv:

uv pip install mcp-ntopng

Configuration

To use the MCP NTOPNG server with Claude Desktop, you'll need to configure the connection to your NTOPNG instance:

  1. Locate your Claude Desktop configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Add the NTOPNG MCP server configuration to this file:

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

  1. Replace the placeholders:

    • /path/to/your/uv-binary: Find with which uv in your terminal
    • <ntopng-host>: Your NTOPNG server hostname
    • <ntopng-dbport>: ClickHouse database port (typically 9000)
    • <ntopng-dbuser>: ClickHouse database username
    • <ntopng-dbpassword>: ClickHouse database password

  2. Restart Claude Desktop to apply the changes.

Environment Variables

The server uses these environment variables for configuration:

Required Variables

  • NTOPNG_HOST: Hostname of the NTOPNG server
  • NTOPNG_DBUSER: Username for ClickHouse DB authentication
  • NTOPNG_DBPASSWORD: Password for ClickHouse DB authentication
  • NTOPNG_API_KEY: NTOPNG authentication token

Optional Variables

  • NTOPNG_DBPORT: Port number for ClickHouse (default: 9000 for HTTPS, 8123 otherwise)
  • NTOPNG_SECURE: Enable TLS connection (default: "false")
  • NTOPNG_VERIFY: Enable SSL certificate verification (default: "true")
  • NTOPNG_CONNECT_TIMEOUT: Connection timeout in seconds (default: 30)
  • NTOPNG_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds (default: 300)

Available Tools

The MCP NTOPNG server provides several tools to query network data:

Interface Information

  • fetch_ntopng_all_ifids: Retrieve all available interface IDs
  • fetch_ntopng_top_local_talkers: Get top 10 local talkers for a specified interface
  • fetch_ntopng_top_remote_talkers: Get top 10 remote talkers for a specified interface

Host Information

  • get_ntopng_hosts_location: Fetch geographical location and additional info for hosts

Alert Statistics

  • get_ntopng_all_alert_stats: Retrieve statistics for all alerts
  • get_ntopng_flow_alert_stats: Get statistics for flow alerts
  • get_ntopng_host_alert_stats: Get statistics for host alerts
  • get_ntopng_interface_alert_stats: Get statistics for interface alerts
  • get_ntopng_mac_alert_stats: Get statistics for MAC alerts
  • get_ntopng_network_alert_stats: Get statistics for network alerts
  • get_ntopng_snmp_device_alert_list: Get list of SNMP device alerts
  • get_ntopng_snmp_device_alert_stats: Get statistics for SNMP device alerts
  • get_ntopng_system_alert_stats: Get statistics for system alerts
  • get_ntopng_user_alert_stats: Get statistics for user alerts

Flow Data

  • query_ntopng_flows_data: Retrieve detailed flows data
  • get_ntopng_top-k_flows: Get top-k flows data

Device Statistics

  • get_ntopng_flow_devices_stats: Get statistics for all flow devices
  • get_ntopng_sflow_devices_stats: Get statistics for all sFlow devices

Database Queries

  • list_tables_ntopng_database: List tables structure of the NTOPNG database
  • query_ntopng_database: Execute custom queries against the NTOPNG ClickHouse database

Usage Examples

After configuring the MCP server in Claude Desktop, you can ask questions about your network monitoring data in natural language.

Example queries:

  • "Show me the top 5 traffic sources in my network"
  • "List all recent security alerts"
  • "What's the geographical distribution of my network connections?"
  • "Show network traffic patterns over the last 24 hours"
  • "Identify potential DDoS attacks in the last week"

The AI assistant will use the appropriate tools to query your NTOPNG database and provide insights based on the data.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later