alpadalar/netops-mcp

A Model Context Protocol server that exposes
26 network and system diagnostic tools — ping, traceroute, mtr, nmap,
DNS queries, HTTP requests, and system monitoring — to MCP clients such as
Claude Desktop, Claude Code, and Cursor. Each tool is a thin, input-validated
wrapper around a standard OS utility. Two transports are supported: **stdio**
(the client launches the server as a subprocess) and **HTTP** (a long-running
server with auth, rate limiting, and metrics).
Features
- **Connectivity** — ping, traceroute, mtr, telnet, netcat
- **DNS** — nslookup, dig, host
- **HTTP / API** — curl, httpie, api_test
- **Discovery & scanning** — nmap_scan, service_discovery, port_scan, service_enumeration
- **Network state** — ss, netstat, arp, arping
- **System monitoring** — status, CPU, memory, disk, process list, tool availability
Requirements
- **Python >= 3.10** and uv (recommended)
- **Linux or macOS** — the network tools are OS-specific; Windows is not supported
- **System tools** on PATH (availability is checked at startup):
curl, ping, traceroute, mtr, telnet, nc, nmap, ss, netstat,
arp, arping, nslookup, dig, host. httpie is optional.
Installation
Alternatives (pip, Docker)
Quick Start
stdio (no auth)
Point an MCP client at this command (see below).
HTTP
HTTP mode **requires an API key by default** and refuses to start without one —
see Authentication. Once a key is configured:
Authentication
> **Breaking change (0.1.0):** HTTP mode now requires an API key by default
> (security.require_auth defaults to true). stdio mode is unaffected (local
> transport, no auth).
On a fresh checkout the HTTP server **fails fast before binding the port** when
no key is configured, printing copy-paste setup instructions plus a freshly
generated example key (never activated automatically).
**1. Generate a key.** The plain key is printed once (never stored);
--config writes only its sha256: digest and enables require_auth:
Flags: -n/--count, -l/--length (default 32), --hash, --json,
--config PATH. To hash an existing key:
python -c "import hashlib;print('sha256:'+hashlib.sha256(b'YOUR-KEY').hexdigest())".
**2. Configure.** Only sha256: digests are accepted — plain keys are
rejected at config load time:
**3. Authenticate.** Clients send the **plain** key (the server stores and
compares only the digest, in constant time). Any of three headers works:
A keyless request returns 401; an invalid key returns 403. /health is
always public; /metrics requires the key while auth is enabled (it is only
public when require_auth: false).
**Opt out** (only on trusted, isolated networks):
Host/port/path resolve as **CLI flags > config server section > built-in
defaults** (0.0.0.0 / 8815 / /netops-mcp). --config falls back to
$NETOPS_MCP_CONFIG when omitted.
Configuration
Configuration is loaded from a JSON file (config/config.json by default, or
$NETOPS_MCP_CONFIG) and validated by Pydantic models. Copy the fully
documented config/config.example.json to get
started. Only five environment variables are read; everything else lives in the
JSON file.
| Env var | Effect |
| --- | --- |
| HTTP_HOST / HTTP_PORT / HTTP_PATH | Forwarded by start_http_server.sh as --host / --port / --path |