NetOps MCP

A Model Context Protocol server that exposes
30 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, reverse_dns_lookup, email_dns_check (MX/SPF/DMARC/DKIM)
• TLS & registry — tls_certificate_check, whois_lookup
• 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.11 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

git clone https://github.com/alpadalar/netops-mcp.git
cd netops-mcp

# Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e .

# pip
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Docker (HTTP mode) — see Authentication before first run
docker compose up -d

Quick Start

stdio (no auth)

uv run netops-mcp          # or: python -m netops_mcp.server

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:

# Pass the config that holds your API key — without it the server loads
# built-in defaults (require_auth: true, no keys) and fails fast.
python -m netops_mcp.server_http --config config/config.json --host 0.0.0.0 --port 8815
# or: NETOPS_MCP_CONFIG=config/config.json python -m netops_mcp.server_http
# or: ./start_http_server.sh   (defaults to config/config.json)

curl http://localhost:8815/health          # health check (no key required)

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:

python scripts/generate_api_key.py                             # print a plain key
python scripts/generate_api_key.py -n 2 --config config/config.json   # write digests

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:<64-hex> digests are accepted — plain keys are
rejected at config load time:

{ "security": { "require_auth": true, "api_keys": ["sha256:<hex-digest-of-your-key>"] } }

3. Authenticate. Clients send the plain key (the server stores and
compares only the digest, in constant time). Any of three headers works:

curl -H "Authorization: Bearer YOUR-KEY" http://localhost:8815/netops-mcp
curl -H "X-API-Key: YOUR-KEY"            http://localhost:8815/netops-mcp
curl -H "API-Key: YOUR-KEY"              http://localhost:8815/netops-mcp

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):

{ "security": { "require_auth": false } }

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.

Most-used config keys (the full model-derived table is regenerable with
python scripts/gen_config_table.py):

MCP Client Configuration

stdio (Claude Desktop / Cursor)

Add to claude_desktop_config.json (Claude Desktop) or .cursor/mcp.json
(Cursor):

{
  "mcpServers": {
    "netops-mcp": {
      "command": "uv",
      "args": ["run", "netops-mcp"],
      "cwd": "/absolute/path/to/netops-mcp"
    }
  }
}

Claude Code adds the same server with one command:

claude mcp add netops-mcp -- uv run netops-mcp

HTTP + API key

Point a client at a running HTTP server, sending the plain key as a header
(.mcp.json / .cursor/mcp.json):

{
  "mcpServers": {
    "netops-mcp": {
      "type": "http",
      "url": "http://localhost:8815/netops-mcp",
      "headers": { "X-API-Key": "YOUR-KEY" }
    }
  }
}

Claude Code can add the same in one command:
claude mcp add --transport http netops-mcp http://localhost:8815/netops-mcp --header "X-API-Key: YOUR-KEY".

Security

Inputs are validated to prevent command injection, and HTTP/scan targets are
resolved then classified so requests to loopback, link-local, and cloud
metadata addresses are blocked by default (private/LAN ranges are allowed).
Privileged nmap scans are gated behind config. In production, run HTTP mode
behind a reverse proxy (nginx, Caddy) for TLS — never expose the plain HTTP port
to the internet. The Docker image runs as a non-root user with only NET_ADMIN

• NET_RAW capabilities and 2 CPU / 1 GB limits (docker-compose.yml).

Responsible use. The scanning tools (nmap_scan, port_scan,
service_enumeration) and other active probes may be illegal without
authorization. Only scan hosts and networks you own or have explicit
permission to test. You are solely responsible for your use of these tools.

See SECURITY.md for the full threat model and the vulnerability
disclosure process.

Contributing

Contributions are welcome — see CONTRIBUTING.md for dev setup,
the test mocking strategy, and PR guidelines. By participating you agree to the
Code of Conduct.

License

MIT — see LICENSE.

Hosted deployment

A hosted deployment is available on Fronteir AI.