netdoctor
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., "@netdoctor My internet is slow—run some network checks and tell me where the problem is."
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.
netdoctor
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 |
|
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. |
Can't run other commands | Only the programs listed below can run, from fixed system folders (never from |
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 |
|
|
|
|
|
|
|
|
|
|
|
|
| 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-mcpClaude 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-mcpclaude mcp add netdoctor -- netdoctor-mcpThe 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 |
|
| replies, packet loss, min/avg/max latency, jitter, a verdict ( |
|
| answers, which resolver replied, lookup time, status ( |
|
| each hop's IP and average delay, silent hops, whether the target was reached, the biggest delay jump |
|
|
|
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 -qThe 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 toolscheck_portARead-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_lookupARead-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
pingARead-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
tracerouteARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Network, domain and website diagnostics for AI clients via MCP.
DNS comparison, Claude and cloud components/incidents, and website diagnostics. Free; no API key.
Free, no-API-key network lookups for AI agents — IP geolocation, DNS, WHOIS, HTTP and SSL/TLS certificate checks, and full domain health reports.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to perform network ping tests and internet connectivity checks.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform real network diagnostics on the local machine, including ping, traceroute, DNS lookups, TLS checks, and more.MIT
- AlicenseAqualityDmaintenanceEnables AI agents to check the health of internet infrastructure and specific services, helping diagnose whether issues are local or external.347 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to debug local networks in plain language by pinging, sweeping subnets, tracing routes, resolving DNS, scanning ports, inspecting ARP tables and active connections, and checking URL reachability.MIT