netops-mcp
Allows extracting domains from Caddy configuration files for TLS certificate expiry checking via the cert_sweep tool.
Allows extracting domains from nginx server blocks for TLS certificate expiry checking via the cert_sweep tool.
Provides tools to inspect WireGuard interface status, generate peer configurations, and manage peers (add/remove) with safety controls and audit logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@netops-mcp why can't I reach api.example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: Tailnet MCP Server
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/hostspin, a VPN route, a captive local resolver. Running on your host,config_correlatereads them directly. That's why it can say/etc/hosts:2 pins api.example.com -> 10.0.0.5; this OVERRIDES DNSwhile a remote probe insists everything is fine.A verdict, not a data dump.
net_triangulateruns 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 probesversusTHEIR SIDE: ... unreachable from you AND from all 3 global probes.net_diagnosewalks 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
execFilewith 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, oropensslshelled out — so it works even in slim containers or locked-down images where those aren't installed.ping/traceroute/wgare 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.
Trust axis | netops-mcp | ProbeOps MCP | ||
Read-only by default | ✓ | — | — | — |
No shell execution | ✓ | — | — | — |
Untrusted-input wrapper | ✓ | ✗ | ✗ | ✗ |
Zero telemetry | ✓ | — | — | ✗ |
Local-first (sees your machine) | ✓ | ✗ | ✗ | ✗ |
WireGuard | ✓ | ✗ | ✗ | ✗ |
Transport | stdio (local) | remote Docker | remote HTTP/SSE | stdio + remote SaaS |
"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
Tool | What |
| One-shot "why can't I reach X" — DNS→ping→TCP→TLS→HTTP, stops at the first failure, returns a verdict |
| Is it me or them? Local probe vs Globalping worldwide probes |
| Full probe battery → shareable Markdown report for bug tickets |
| Cross-check |
| Interfaces + resolvers + WireGuard snapshot |
Single probes
Tool | What |
| A/AAAA/MX/TXT/NS/CNAME, custom resolver |
| ICMP with TCP-ping fallback (no root needed) |
| Connectivity check of named ports (capped — not a scan) |
| Cert chain, expiry, SANs, protocol/cipher, handshake timing |
| Status, redirects, DNS/connect/TLS/TTFB timing breakdown |
| Hop-by-hop path to a host with per-hop latency |
| Path-MTU discovery; catches MTU black holes (VPN "connects then hangs") |
| TLS expiry across many domains — auto-extracts them from nginx/Caddy/Traefik/compose |
Tunnel & proxy
Tool | What |
| Direct vs interface/tunnel egress identity & reachability — split-tunnel leak detection |
| Egress IP + which resolvers you actually use (leak heuristics) |
WireGuard
Tool | What | Gated? |
| Interfaces/peers, stale-handshake flags | read-only |
| Fresh keypair + ready-to-paste client config | read-only |
| Add/update a peer |
|
| Remove a peer |
|
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:mcpbproducesnetops-mcp.mcpbfrom 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
Restart the client fully after editing
mcp.json— most clients read it only at startup, not on save.Run it once by hand:
npx -y netops-mcp. A healthy server prints[netops] netops-mcp vX.Y.Z ready on stdioto stderr and then waits silently (it speaks MCP over stdin/stdout — no further output is normal). Ifnpxerrors here, fix that first.Check Node ≥ 20:
node --version. Older Node is the most common silent failure.
Reference & advanced
Flags & env
Flag / Env | Effect |
| Disable all outbound third-party calls (Globalping, egress echo) |
| Allow mutating WireGuard ops ( |
| Silence the stderr audit log |
| Comma/space list of allowed targets (host or CIDR) — strict mode |
| Denylist of targets |
| Cap for |
| Override the hosts-file path (used by |
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_pingfalls back to a TCP connect if it's missing;mtu_blackholeneeds it.traceroute(tracerton Windows) — fortraceroute.wg(wireguard-tools) — for the WireGuard tools.
Platform | Status |
Linux | First-class. All tools work given the optional binaries. |
macOS | Works. Caveat: macOS doesn't use |
Windows | Partial. Pure-Node probes (DNS/TCP/TLS/HTTP) work; |
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.7cert_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 devDemo
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
Available Tools
19 toolscert_sweepTLS certificate sweepARead-onlyIdempotent
Check TLS certificate expiry across many domains at once. Pass an explicit list, and/or config paths (nginx/Caddy/Traefik/compose files or dirs) to auto-extract the domains. Sorts by soonest expiry and flags certs expiring within warn_days.
Inputs: port, paths, domains, warn_days.
config_correlateCorrelate local config with live DNSARead-onlyIdempotent
Reads /etc/hosts and resolv.conf and cross-checks them against live DNS — surfaces the hidden config that explains weird resolution (stale /etc/hosts pin, overriding resolver). No remote service can do this.
Inputs: domain.
diagnosis_bundleShareable diagnosis reportARead-onlyIdempotent
Runs a full battery of probes against a target and returns a clean Markdown report you can paste straight into a bug report or support ticket. Includes DNS, reachability, TLS, HTTP timing, optional global probes, and local context.
Inputs: target (required), include_global.
dns_leak_checkDNS leak / egress identityARead-onlyIdempotent
Reports your public egress IP and the DNS resolvers your system is actually using, and flags whether resolvers look like a local/ISP server (potential leak) vs a tunnel resolver. Heuristic. Needs network access for egress IP.
Inputs: no named parameters.
dns_lookupDNS lookupARead-onlyIdempotent
Resolve DNS records for a name. Supports A/AAAA/MX/TXT/NS/CNAME/SOA and an optional custom resolver. Use this when you ONLY need to check DNS resolution. For a full 'why can't I reach X' verdict that also checks ping/TCP/TLS/HTTP, use net_diagnose instead.
Inputs: name (required), type, server.
http_probeHTTP probeARead-onlyIdempotent
GET a URL and report status, redirect chain, server header, and a timing breakdown (DNS / connect / TLS / TTFB / total).
Inputs: url (required).
mtu_blackholeMTU black-hole detectorARead-onlyIdempotent
Path-MTU discovery via Don't-Fragment pings. Detects the classic MTU black hole — small packets pass, large ones vanish with no ICMP reply — the reason connections establish but then hang on big transfers over VPN/PPPoE links.
Inputs: host (required).
net_diagnoseDiagnose connectivity (why can't I reach X)ARead-onlyIdempotent
One-shot diagnosis: resolves DNS, pings, checks TCP, inspects TLS, and probes HTTP for a target, then returns a verdict on where the failure is.
Inputs: target (required).
net_overviewNetwork overviewARead-onlyIdempotent
Snapshot of local interfaces, resolvers, and WireGuard interfaces — quick context for the assistant.
Inputs: no named parameters.
net_pingPing hostARead-onlyIdempotent
Reachability check. Uses ICMP ping when available, falls back to a TCP connect (works without root). Use this when you ONLY need to know if a host is alive. It does NOT check application ports or HTTP — for that use tcp_port_check or net_diagnose.
Inputs: host (required), tcp_port.
net_triangulateIs it me or them? (local + global probes)ARead-onlyIdempotent
Runs the same reachability test from THIS machine and from Globalping's worldwide probes, then verdicts whether a failure is your side, your network/ISP, or the target. Disabled in --local-only mode.
Inputs: target (required), locations.
tcp_port_checkTCP port checkARead-onlyIdempotent
Check whether specific TCP ports on a host accept connections. This is a connectivity check of named ports — NOT a discovery scan. Capped by scope-guard. Use this when you need to verify a SPECIFIC port is open at the TCP level. It does NOT send HTTP or check TLS. Use after net_ping confirms the host is alive, or when ICMP is blocked.
Inputs: host (required), ports (required).
tls_inspectTLS / certificate inspectARead-onlyIdempotent
Open a TLS connection and report certificate chain, expiry (days), SANs, protocol, cipher, handshake timing, and validation status.
Inputs: host (required), port.
tracerouteTracerouteARead-onlyIdempotent
Trace the network path to a host hop by hop, with per-hop latency. Wraps system traceroute/tracert.
Inputs: host (required), max_hops.
tunnel_diffDirect vs tunnel diffARead-onlyIdempotent
Compares egress identity and reachability from the default route vs. bound to a specific interface IP (e.g. your VPN interface). Reveals split-tunnel surprises and egress differences. Needs network access for the egress check.
Inputs: url, interface_ip.
wg_config_generateGenerate WireGuard peer configARead-onlyIdempotent
Generate a fresh WireGuard keypair and a ready-to-paste client config. Read-only — it does NOT modify any interface; it just prints the config and keys for you to use.
Inputs: dns, address, allowed_ips, server_endpoint, +1 more.
wg_peer_addAdd / update WireGuard peerADestructive
Add or update a peer on a WireGuard interface (wg set). Mutating: requires --enable-write, and runs as a dry-run unless confirm:true. Needs privileges to apply.
Inputs: iface (required), public_key (required), allowed_ips (required), confirm, +1 more.
wg_peer_removeRemove WireGuard peerADestructive
Remove a peer from a WireGuard interface (wg set ... remove). Mutating: requires --enable-write, and runs as a dry-run unless confirm:true.
Inputs: iface (required), public_key (required), confirm.
wg_statusWireGuard statusARead-onlyIdempotent
Reads WireGuard interfaces and peers (via wg show): handshake recency, endpoints, allowed-IPs, transfer. Read-only. Flags peers with stale handshakes.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes, especially the WireGuard and diagnostic tools. However, there is some overlap among net_diagnose, diagnosis_bundle, and net_triangulate that could cause confusion, though descriptions help differentiate.
Naming patterns are inconsistent: some tools use verb_noun (e.g., dns_lookup, http_probe), others noun_verb (e.g., tcp_port_check, tls_inspect), and some use prefixes like 'net_' or 'wg_'. While still readable, the mix reduces predictability.
With 19 tools, the server covers network diagnostics, DNS, TLS, MTU, traceroute, and WireGuard management comprehensively. Each tool addresses a specific need without being excessive.
The tool surface is largely complete for network operations, covering diagnosis, DNS, TLS, connectivity, and WireGuard configuration. Minor gaps exist, such as missing routing table inspection or interface configuration, but core workflows are well-supported.
Maintenance
Related MCP Connectors
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Deploy local apps, add managed Postgres, and inspect logs from your AI coding agent.
Query your app's logs, metrics and incidents from your AI assistant.
Network, domain and website diagnostics for AI clients via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform real network diagnostics on the local machine, including ping, traceroute, DNS lookups, TLS checks, and more.MIT
- AlicenseNot gradedqualityDmaintenanceQuery devices, check connectivity, and get network status from your Tailscale tailnet directly via an AI assistant.1MIT
- AlicenseAqualityDmaintenanceEnables AI agents to check the health of internet infrastructure and specific services, helping diagnose whether issues are local or external.347 npmISC
- AlicenseNot gradedqualityDmaintenanceDiagnoses proxy misconfigurations that break AI coding tools like Cursor, VS Code, and Windsurf.1MIT