netdiag-mcp

An MCP server that gives an AI agent read-only network diagnostics for a target host: DNS, TLS, HTTP and registry data.

Agents are good at reasoning about infrastructure problems and bad at gathering the facts. "Why is this domain not loading?" needs a resolver, a certificate, a redirect chain and a registry lookup — four different tools, none of which an LLM can do on its own. This server supplies them.

No API keys. Every backing service is keyless, so it runs the moment you clone it.

Install and run

uv sync
uv run netdiag-mcp        # speaks MCP over stdio

Register it with any MCP client. For Claude Desktop, in claude_desktop_config.json:

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

Related MCP server: External Reconnaissance MCP Server

Tools

Each is annotated readOnlyHint so a client can auto-approve it safely.

Design notes

NXDOMAIN is a result, not an error. dns_lookup returns {"nxdomain": true, "records": []}. "This domain does not exist" is usually the answer the agent wanted, and burying it in an exception makes it harder to reason about.

A failed certificate check is also a result. tls_certificate returns valid: false with the verification message rather than raising — an expired or mismatched cert is frequently the thing being investigated.

Errors come back as {"error": ...}. A tool call that raises gives an agent nothing to work with. Every failure path returns a dict describing what went wrong.

Security

These tools accept a hostname from a language model and then make a network request to it. That is a textbook SSRF surface: without a guard, an agent could be talked into using this server to reach 169.254.169.254 (cloud metadata), 127.0.0.1, or anything on an internal RFC1918 network.

resolve_public() resolves the target and refuses it unless every returned address is publicly routable. Checking every answer matters — a hostile domain can return one public and one private record and win the race if only the first is inspected.

Three details that are easy to get wrong, and are covered by tests:

• Redirects are re-checked at every hop. A public URL is allowed to redirect to 127.0.0.1. Following redirects with follow_redirects=True would validate only the first URL, so the chain is walked by hand.

• Opaque schemes. data: and javascript: contain no ://, so a check for :// misses them entirely.

• example.com:8080 is not a scheme. URL scheme grammar permits dots, so a bare host:port matches the scheme pattern exactly and must not be rejected as one.

Tests

uv run pytest -m "not integration"   # 62 offline tests
uv run pytest                        # adds 3 that need the network

Validation and the SSRF guard are tested offline on purpose: they are the parts that must not regress, and they should not need a working internet connection to verify.

Requirements

Python 3.12+, mcp>=2.0. Note that MCP SDK 2.0 renamed FastMCP to MCPServer; this targets the 2.x API.

Licence

MIT