netops-mcp

• What is this?

• Why it's different

• A network tool you can hand your assistant safely

• What you actually get back

• Tools (v0.1)

• Install

• Reference & advanced

  • Flags & env

  • Requirements & platform support

  • The shareable report

  • cert_sweep: point it at your reverse proxy

• Develop

• Demo

• Roadmap (v0.2+)

• Contributing

• License

What is this?

The site loads for everyone but you. Your assistant runs ping/dig/curl, dumps three screens of records, RTTs and exit codes, and leaves you to decode them. A cloud uptime checker is no better — it pings from its own data center, sees the public internet is fine, and reports "up." True for the data center, useless to you: the checker was never on your machine, so it can't see the reason.

netops-mcp runs on your machine. That single fact unlocks the layer cloud probes are structurally blind to — your /etc/hosts, your VPN routes, your local resolvers, your homelab. It walks every hop between you and the host (DNS → ping → TCP → TLS → HTTP), cross-checks against worldwide probes via Globalping, and returns a verdict instead of raw output: which side the fault is on, and why.

So when a site is "down for you but up for the world," you don't get "ping says 100% loss." You get "/etc/hosts:2 pins it to a dead 10.0.0.5; that's why." — the catch a remote probe can't make, because the offending line lives on your disk.

   Cloud checker                      netops-mcp (on YOUR machine)
   ─────────────                      ────────────────────────────
   probes from a data center          probes from where YOU are
   sees: the public internet          sees: /etc/hosts, VPN, resolvers,
                                             homelab — AND the public net
        │                                   │
        ▼                                   ▼  DNS→ping→TCP→TLS→HTTP
   "Site is up. ✓"                     + Globalping: up elsewhere?
   (true — and no help                      │
    to you)                                 ▼
                              "YOUR SIDE: down for you but reachable
                               from 3/3 global probes. /etc/hosts:2
                               pins it to a stale 10.0.0.5 — remove it."

In short: a translator between "the network is broken" and "here's the exact line that's breaking it." Raw output tells you what happened; netops-mcp tells you what to do about it.

Related MCP server: connectivity-diagnostics

Why it's different

• Sees what cloud probes structurally can't. A SaaS checker fires from its own data center, so it's blind to the things that actually break a site for you — a stale /etc/hosts pin, a VPN route, a captive local resolver. Running on your host, config_correlate reads them directly. That's why it can say /etc/hosts:2 pins api.example.com -> 10.0.0.5; this OVERRIDES DNS while a remote probe insists everything is fine.

• A verdict, not a data dump. net_triangulate runs the same reachability test from your machine and from Globalping, then names the side at fault: YOUR SIDE: api.example.com is down for you but reachable from 3/3 global probes versus THEIR SIDE: ... unreachable from you AND from all 3 global probes. net_diagnose walks DNS → ping → TCP → TLS → HTTP locally and verdicts where the chain breaks. One answer with the raw probes underneath it — not a wall of output to interpret yourself.

• Safe by default. Read-only. No shell — every system call is execFile with an argv array, never a string, so there's nothing for a hostile hostname to inject into. Untrusted output is wrapped before it reaches the model, anti-scan caps and allow/deny lists are on, audit goes to stderr, and telemetry is zero. WireGuard writes are flag-gated and dry-run unless you confirm. That safety is also why the verdicts are trustworthy: every claim ships with the raw data under it, so you verify rather than take it on faith. See SECURITY.md.

• Few moving parts. DNS, TCP, TLS and HTTP probing are pure Node — no dig, curl, or openssl shelled out — so it works even in slim containers or locked-down images where those aren't installed. ping / traceroute / wg are used when present and skipped gracefully when not.

A network tool you can hand your assistant safely

Giving an AI assistant a network tool means giving it a blast radius. The defenses below are verifiable by reading the source — not promises from a vendor dashboard. Every netops-mcp cell is backed by code you can audit before you run it; competitor cells follow published behavior, and axes we can't confirm from the outside are left blank rather than guessed.

"No shell" means every system call goes through execFile with an argv array — never a shell string — so a hostile hostname has nothing to inject into. The "untrusted-input wrapper" fences off any string that came from the network (DNS records, cert fields, HTTP status lines) before it reaches the model, blunting prompt-injection via DNS TXT or banners. Read the security model for the full threat picture.

What you actually get back

The verdicts below are the real strings the tools emit — not marketing paraphrase.

net_triangulate — is it me or them?

YOUR SIDE: api.example.com is down for you but reachable from 4/4 global probes.
The target is up — problem is your machine, network, DNS, or ISP routing.

THEIR SIDE: api.example.com is unreachable from you AND from all 4 global probes.
The target is down.

config_correlate — the stale-pin catch no remote probe can make:

/etc/hosts:2 pins api.example.com -> 10.0.0.5; this OVERRIDES DNS (DNS itself
returns nothing). If api.example.com seems stuck on an old address, this line is why.

net_diagnose — one-shot, short-circuits at the first failing layer:

DNS resolves (93.184.216.34) but TCP/443 is closed/filtered. Firewall, the service
is down, or wrong port. ICMP also fails.

Tools (v0.1)

Diagnose & orchestrate

Single probes

Tunnel & proxy

WireGuard

Install

Claude Desktop — one click, no JSON

Download netops-mcp.mcpb from the latest release and double-click it. Claude Desktop opens an install dialog where you can toggle local-only mode, WireGuard writes, and the allow/deny lists — no config file to hand-edit. Done.

Building it yourself: npm run build:mcpb produces netops-mcp.mcpb from source.

Claude Code / Cursor / manual — mcp.json

{
  "mcpServers": {
    "netops": {
      "command": "npx",
      "args": ["-y", "netops-mcp"]
    }
  }
}

The -y flag is required — without it, npx may stop to prompt on first run and the server never starts.

On Windows, npx is a shell script, so the launcher needs cmd /c to find it:

{
  "mcpServers": {
    "netops": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "netops-mcp"]
    }
  }
}

Privacy-strict (no third-party calls at all — disables Globalping and the egress-IP echo) — add --local-only to args:

{
  "mcpServers": {
    "netops": {
      "command": "npx",
      "args": ["-y", "netops-mcp", "--local-only"]
    }
  }
}

Don't see the tools? Three checks

1. Restart the client fully after editing mcp.json — most clients read it only at startup, not on save.

2. Run it once by hand: npx -y netops-mcp. A healthy server prints [netops] netops-mcp vX.Y.Z ready on stdio to stderr and then waits silently (it speaks MCP over stdin/stdout — no further output is normal). If npx errors here, fix that first.

3. Check Node ≥ 20: node --version. Older Node is the most common silent failure.

Reference & advanced

Flags & env

Requirements & platform support

• Node ≥ 20. No other hard dependency — DNS/TCP/TLS/HTTP probes are pure Node.

• Optional system binaries, used when on PATH, gracefully skipped otherwise:

  • ping — net_ping falls back to a TCP connect if it's missing; mtu_blackhole needs it.

  • traceroute (tracert on Windows) — for traceroute.

  • wg (wireguard-tools) — for the WireGuard tools.

Applying WireGuard changes (wg set) needs root / CAP_NET_ADMIN — the server never auto-escalates; it surfaces the error if it lacks privilege.

The shareable report

diagnosis_bundle renders a full probe battery as paste-ready Markdown — drop it straight into a bug ticket or a Slack thread:

# netops-mcp diagnosis — `api.example.com`
_2026-06-13T10:04:11Z_

**Verdict:** Reaches the host but TLS chain is invalid — their side.

## DNS
- A: 93.184.216.34 (12ms)
## Reachability
- ping: reachable via tcp 18ms
- TCP/443: open (21ms)
## TLS
- TLSv1.3 TLS_AES_256_GCM_SHA384, handshake 41ms
- cert: 3d left (2026-06-16), valid chain
## From the world (Globalping)
- Amsterdam: ✓ loss 0% avg 12ms
- New York: ✓ loss 0% avg 81ms
## Local context
- resolvers: 1.1.1.1, 8.8.8.8
- egress IP: 203.0.113.7

cert_sweep: point it at your reverse proxy

Instead of listing domains by hand, give cert_sweep a config path and it extracts the hostnames itself — from nginx server_name, Traefik Host(`…`) labels, Caddy site blocks, and compose files — then reports expiry soonest-first:

cert_sweep  config_path: /etc/nginx/sites-enabled/

⚠ shop.example.com   — expires in 6d  (2026-06-19)
✓ api.example.com    — 71d left
✓ www.example.com    — 71d left
Checked 3 domains — 1 needs attention (≤21d or expired), 0 unreachable.

Develop

npm install
npm run build
npm run smoke      # boots the server, asserts the 19-tool handshake
node dist/index.js # or: npm run dev

Demo

The animation is a real recording of the server: vhs demo/demo.tape drives demo/cli.mjs, where config_correlate is a genuine call against demo/hosts.fixture. The two probe lines above it (net_diagnose, net_triangulate) show what an agent would run; the stale-pin catch is the live call. The regenerate demo gif GitHub Action re-renders assets/cli.gif from the tape.

Roadmap (v0.2+)

dns_diagnose (deep), mtr-style continuous path stats, HTTP/SSE transport, an opt-in --enable-scan nmap mode behind an allowlist.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Found a security issue? Please open a private advisory rather than a public issue (details in SECURITY.md).

License

MIT