Skip to main content
Glama

netdoctor

CI License: MIT Python 3.10+ Windows | macOS | Linux

Ask Claude why your internet is slow, and let it check.

netdoctor is a small MCP server that gives Claude four safe, read-only network checks: ping, dns_lookup, traceroute and check_port. Claude runs them on your computer, reads the summarised results, and tells you where the problem is: your Wi-Fi, your router, your ISP, DNS, or the site itself.

You:    My internet feels really slow today.
Claude: (pings your router, then 1.1.1.1, looks up a name, traces the route)
        Your router answers in 2 ms, so Wi-Fi is fine. Latency jumps from 9 ms to
        180 ms at hop 3, inside your ISP's network, and 1.1.1.1 shows 20% packet
        loss. DNS is fast. The slowdown is on your ISP's side.

Safe by design

Promise

How it is kept

Runs locally

The server runs on your computer over stdio. It has no web server and listens on no port.

Sends nothing anywhere

No telemetry, no analytics, no update checks, no server owned by this project. The only traffic is the check you asked for. Results go only to your own Claude session. A test fails the build if any web or HTTP library is imported.

Read-only

It never changes settings, installs anything or writes files. It has no "fix it" features: no DNS changes, no adapter resets.

No admin rights

Every check works as a normal user.

Not a scanning tool

check_port takes exactly one host and one port. Ranges, lists and CIDR blocks are rejected. In any 10 minutes it will check at most 5 different ports on one machine and at most 10 different machines. Limits are counted per resolved IP address, so other spellings of the same machine share its budget.

Can't flood

All tools are rate-limited: at least 1 second between checks, at most 20 a minute, port checks at most 10 a minute, and never more than 2 checks running at once. ping sends at most 10 packets. Broadcast, multicast and numeric shorthand such as 0xffffffff are refused.

Can't run other commands

Only the programs listed below can run, from fixed system folders (never from PATH), with fixed arguments and shell=False. Inputs that start with - (command options), non-ASCII names and IPv6 zone IDs are rejected. Tests check all of this.

Private and loopback addresses (like your router at 192.168.1.1) are allowed on purpose: checking them is often the first step in finding a home network problem.

Why it is not a port scanner

Port scanning means knocking on many doors to see which ones open. Network owners treat it as a sign of attack, and it can get you blocked or in trouble. netdoctor only answers "can I reach this one service?" (for example, "is port 443 on my website reachable?"). It looks up the name, opens one normal TCP connection to one address, the same as a browser does, closes it at once and sends no data. The rate limiter refuses requests that look like a scan, so it can't be turned into one, even by mistake.

Related MCP server: connectivity-diagnostics

Every command netdoctor can run

These are the only programs it can start. <host> is always one validated hostname or IP address, and the numbers are bounded.

Tool

Windows

macOS

Linux

ping

C:\Windows\System32\PING.EXE -n <1-10> -w 2000 <host>

/sbin/ping -n -c <1-10> -W 2000 <host> (IPv6: /sbin/ping6 -n -c <1-10> <host>)

/usr/bin/ping -n -c <1-10> -W 2 <host>

dns_lookup

C:\Windows\System32\nslookup.exe -type=<T> -timeout=3 -retry=1 <name> [server]

/usr/bin/nslookup (same flags)

/usr/bin/nslookup (same flags)

traceroute

C:\Windows\System32\TRACERT.EXE -d -h <1-30> -w 1000 <host>

/usr/sbin/traceroute -n -m <1-30> -w 1 -q 3 <host>

traceroute -n -m <1-30> -w 1 -q 3 <host>, or tracepath -n -m <1-30> <host> if traceroute is missing

check_port

no program: one TCP connection from Python, 3-second timeout

same

same

<T> is one of A, AAAA, CNAME, MX, NS, TXT. On Linux the program may also be found in /bin or /usr/sbin; the full list is in src/netdoctor/runner.py.

Install

You need Python 3.10+ and uv (for uvx).

Claude Code (one line):

claude mcp add netdoctor -- uvx netdoctor-mcp

Claude Desktop: add this to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "netdoctor": {
      "command": "uvx",
      "args": ["netdoctor-mcp"]
    }
  }
}

Without uv (using pipx):

pipx install netdoctor-mcp
claude mcp add netdoctor -- netdoctor-mcp

The package is netdoctor-mcp on PyPI (the name netdoctor there belongs to an unrelated project). netdoctor is also listed in the official MCP Registry as io.github.musahyderr/netdoctor. Every release is built and published by GitHub Actions from a tagged commit, using PyPI trusted publishing (no stored tokens).

Tools

Tool

Arguments

What you get back

ping

host, count (1-10, default 4)

replies, packet loss, min/avg/max latency, jitter, a verdict (good, degraded, unreachable, dns_failure) and a one-line summary

dns_lookup

name, record_type (default A), server (optional, e.g. 1.1.1.1)

answers, which resolver replied, lookup time, status (ok, nxdomain, timeout, servfail, no_records)

traceroute

host, max_hops (1-30, default 15)

each hop's IP and average delay, silent hops, whether the target was reached, the biggest delay jump

check_port

host, port (one port, 1-65535)

open, closed, no_response, dns_failure or error, connect time

Every result has ok: true/false. Rejected or rate-limited calls come back with ok: false and a plain-English error, and nothing is run.

Try asking Claude things like:

  • "My internet is slow. Can you figure out why?"

  • "Is it my DNS? Compare my DNS with 1.1.1.1."

  • "Why can't I reach github.com?"

  • "Is port 443 open on example.com?"

Development

python -m venv .venv
.venv/bin/pip install -e ".[test]"      # Windows: .venv\Scripts\pip
.venv/bin/pytest -q

The tests never touch the network or start a real program. A guard in tests/conftest.py makes any such attempt fail, and command output comes from captured samples in tests/fixtures/. tests/test_safety.py reads the source code itself to prove the safety rules: only runner.py may import subprocess, shell=True never appears, there is no eval/exec/os.system, and no web libraries are used. CI runs on Ubuntu, Windows and macOS.

Known limitation: the parsers expect English command output. On Windows set to another language, results still come back but some fields may be empty.

Security

See SECURITY.md to report a problem privately.

License

MIT © Syed Musa Hyder. Provided "as is", without warranty of any kind.

Available Tools

4 tools
check_portA
Read-onlyIdempotent

Check whether ONE TCP port on ONE host accepts connections (e.g. 443 for a website). Opens one normal connection and closes it; sends no data. Not a port scanner: limited to a few different ports per host every 10 minutes.

Inputs: host (required), port (required). Returns: object

dns_lookupA
Read-onlyIdempotent

Look up one DNS name and time the lookup. record_type: A, AAAA, CNAME, MX, NS or TXT. server: optional resolver to ask instead of the system one (e.g. 1.1.1.1), useful to tell whether the local DNS is the problem.

Inputs: name (required), server, record_type. Returns: object

pingA
Read-onlyIdempotent

Ping one host (hostname or IP) to see if it is reachable, with latency, jitter and packet loss. count: 1-10 pings (default 4).

Inputs: host (required), count. Returns: object

tracerouteA
Read-onlyIdempotent

Trace the network path to one host and show the delay at each hop, to find where traffic slows down or stops. max_hops: 1-30 (default 15). Takes up to a minute or two.

Inputs: host (required), max_hops. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct diagnostic layer: ICMP reachability (ping), name resolution (dns_lookup), path latency (traceroute), and TCP reachability (check_port). There is no plausible case where an agent would confuse these, and check_port's description explicitly disclaims port scanning.

    Naming Consistency3/5

    Two tools are bare command names (ping, traceroute) while the others use differing orders: noun_verb (dns_lookup) and verb_noun (check_port). The names are all readable and snake_case, but the underlying convention is mixed rather than a single predictable pattern.

    Tool Count5/5

    Four tools is exactly the right scope for a focused network diagnostic server, covering the core checks without padding. Each tool has a clear, non-redundant job.

    Completeness4/5

    Reachability, DNS, path tracing, and port checks cover the main triage workflow, with useful options like custom resolvers and hop limits. Minor gaps remain: no reverse DNS/PTR lookup, no HTTP/TLS handshake verification, and no batch or multi-host variant for comparing targets.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers