网络监控 MCP 服务器

NetBeez MCP Server

A Model Context Protocol (MCP) server that connects LLM clients (Cursor, Claude Desktop, etc.) to the NetBeez network monitoring platform. Enables AI-assisted network troubleshooting, monitoring analysis, and incident investigation.

Features

• 32 tools for querying and managing agents, agent groups, targets, tests, scheduled test templates, alerts, incidents, WiFi profiles, statistics, path analysis, and running ad-hoc Iperf/speed/VoIP/custom command tests (including multiagent run status)
• 5 resources providing the LLM with NetBeez data model knowledge, cross-agent correlation methodology, troubleshooting workflows, full API reference, and ad-hoc test guidance
• 5 prompt templates for common workflows: troubleshoot target, analyze agent health, investigate incident, network overview, run ad-hoc tests
• Dual transport: stdio (for Cursor/Claude Desktop) and HTTP (for remote clients)

Quick Start (Recommended)

Run the one-line installer — it handles everything: Node.js, dependencies, build, credentials, and MCP client configuration:

curl -fsSL https://raw.githubusercontent.com/netbeez/nb-mcp-server/main/install.sh | bash

The installer will prompt you for:

1. Your NetBeez instance URL (e.g. https://demo1.netbeezcloud.net)
2. Your API key (from Dashboard → Settings → API Keys)
3. SSL verification preference (disable for self-signed certs)
4. Which MCP clients to configure (Cursor, Claude Desktop, Windsurf, Codex, Kiro)

The script is idempotent — re-run it any time to update to the latest version or change your configuration.

Quick Start (Windows)

Run the one-line installer from PowerShell — it handles everything: Node.js, dependencies, build, credentials, and MCP client configuration:

irm https://raw.githubusercontent.com/netbeez/nb-mcp-server/main/install.ps1 | iex

The installer will prompt you for the same values as the Unix installer (instance URL, API key, SSL preference, and which MCP clients to configure). It is idempotent — re-run it any time to update or change your configuration.

If execution policy blocks a local run, use:

powershell -ExecutionPolicy Bypass -File .\install.ps1

Development install (no git push required)

From a clone of this repo, run the installer with --dev to point Cursor, Claude Desktop, Codex, Windsurf, and Kiro at your local build:

./install.sh --dev
# or from anywhere:
bash ~/path/to/nb-mcp-server/install.sh --dev

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 --dev

Do not use cat install.sh | bash or irm install.ps1 | iex for development mode — those invocations receive no --dev flag and will download to the default install directory.

This skips cloning; it uses the current directory, runs npm install and npm run build, then configures the same MCP clients to use ./dist/index.js. After making changes, run npm run build and restart the client — no need to push to git to test.

What the installer does

Prerequisites

If you prefer to install manually, you'll need:

• Node.js 18+
• A NetBeez BeezKeeper instance with API access
• An API key (Dashboard → Settings → API Keys)

The one-line installer only requires Node.js 18+ and curl (macOS/Linux) or PowerShell 5.1+ (Windows). No git required.

Manual Installation

1. Download & build

curl -fsSL https://github.com/netbeez/nb-mcp-server/archive/refs/heads/main.tar.gz -o nb-mcp-server.tar.gz
tar -xzf nb-mcp-server.tar.gz && cd nb-mcp-server-main
npm install
npm run build

2. Configure

Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env:

NETBEEZ_BASE_URL=https://your-instance.netbeezcloud.net
NETBEEZ_API_KEY=your-api-key-here

3. Run

npm start

MCP Client Configuration

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json on macOS/Linux, $env:USERPROFILE\.cursor\mcp.json on Windows):

{
  "mcpServers": {
    "netbeez": {
      "command": "node",
      "args": ["~/.netbeez-mcp/dist/index.js"],
      "env": {
        "NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
        "NETBEEZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/Claude/claude_desktop_config.json on Linux, $env:APPDATA\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "netbeez": {
      "command": "node",
      "args": ["~/.netbeez-mcp/dist/index.js"],
      "env": {
        "NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
        "NETBEEZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json on macOS/Linux, $env:USERPROFILE\.codeium\windsurf\mcp_config.json on Windows):

{
  "mcpServers": {
    "netbeez": {
      "command": "node",
      "args": ["~/.netbeez-mcp/dist/index.js"],
      "env": {
        "NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
        "NETBEEZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Codex

Add to your Codex config (~/.codex/config.toml on macOS/Linux, $env:USERPROFILE\.codex\config.toml on Windows):

[mcp_servers.netbeez]
command = "node"
args = ["~/.netbeez-mcp/dist/index.js"]

[mcp_servers.netbeez.env]
NETBEEZ_BASE_URL = "https://your-instance.netbeezcloud.net"
NETBEEZ_API_KEY = "your-api-key-here"

Kiro

Add to your Kiro user MCP config (~/.kiro/settings/mcp.json on macOS/Linux, $env:USERPROFILE\.kiro\settings\mcp.json on Windows):

{
  "mcpServers": {
    "netbeez": {
      "command": "node",
      "args": ["~/.netbeez-mcp/dist/index.js"],
      "env": {
        "NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
        "NETBEEZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Kiro also supports workspace-level MCP config at .kiro/settings/mcp.json.

Tip: The installer (curl | bash or irm | iex above) writes these config files automatically.

Updating

Re-run the installer to pull the latest version and rebuild:

curl -fsSL https://raw.githubusercontent.com/netbeez/nb-mcp-server/main/install.sh | bash

irm https://raw.githubusercontent.com/netbeez/nb-mcp-server/main/install.ps1 | iex

Your existing credentials will be shown as defaults — press Enter to keep them.

If you installed with --dev, run npm run build in the repo and restart your MCP client to pick up changes.

Uninstalling

rm -rf ~/.netbeez-mcp

Remove-Item -Recurse -Force "$env:USERPROFILE\.netbeez-mcp"

Then remove the "netbeez" entry from your MCP client config file(s).

Environment Variables

Tools (32)

Agent Tools (6)

Agent Group Tools (4)

Target Tools (6)

Test & Results Tools (3)

Scheduled Test Tools (5)

Alert & Incident Tools (2)

Statistics Tools (3)

Ad-hoc & Other (3)

Resources (5)

Prompts (5)

Development

# Build
npm run build

# Watch mode
npm run dev

# Test with MCP Inspector
npm run inspect

Architecture

src/
├── index.ts                  # Entry point, transport setup
├── server.ts                 # MCP server definition, registration
├── config.ts                 # Environment variable loading
├── api/
│   ├── base-client.ts        # Shared HTTP client (fetch, retries, errors)
│   ├── jsonapi-client.ts     # JSON:API client (Bearer auth, filters, pagination)
│   ├── legacy-client.ts      # Legacy API client (API-VERSION v1)
│   └── types.ts              # TypeScript types for all entities
├── tools/
│   ├── agents.ts             # Agent tools (6)
│   ├── agent-groups.ts       # Agent group tools (4)
│   ├── targets.ts            # Target tools (6)
│   ├── tests.ts              # Test tools (2)
│   ├── incidents.ts          # Incident tools (1)
│   ├── alerts.ts             # Alert tools (1)
│   ├── wifi.ts               # WiFi tools (1)
│   ├── scheduled-tests.ts    # Scheduled test template & results tools (5)
│   ├── statistics.ts         # Statistics tools (3)
│   ├── path-analysis.ts      # Path analysis tools (1)
│   ├── actions.ts            # Ad-hoc test tools (2): run_adhoc_test, get_multiagent_test_run_status
│   └── ad-hoc.ts             # Re-exports actions for ad-hoc tests
├── resources/
│   ├── data-model.ts         # Entity relationships and data shapes
│   ├── correlation-guide.ts  # Cross-agent correlation patterns
│   ├── troubleshooting-guide.ts
│   ├── api-reference.ts      # API endpoint reference
│   └── ad-hoc-tests.ts       # Ad-hoc tests payloads and result parsing guide
└── prompts/
    ├── troubleshoot-target.ts
    ├── analyze-agent-health.ts
    ├── investigate-incident.ts
    ├── network-overview.ts
    └── run-adhoc-test.ts

API Coverage

The server communicates with two NetBeez API layers:

• JSON:API (primary): All entity and relationship endpoints using Authorization: Bearer <key> authentication. Supports filtering, pagination, includes, and ordering.
• Legacy API: Three statistics endpoints (nb_test_statistics, nb_agent_statistics, access_point_metrics) using Authorization: <key> + API-VERSION: v1 headers.

License

MIT