# ip-doctor 🩺

**Live reputation, network type & abuse score for any IP or domain — from real DNS lookups, no API key.**

`ip-doctor` is both:

- an **MCP server** (`npx -y ip-doctor-mcp`) you add to Claude, Cursor or any agent, and
- a **pay-per-call HTTP API** gated by [x402](https://x402.org) (USDC on Base) — no sign-up, no key.

Give it an IP address or a domain and get back a `CLEAN` / `LOW_RISK` / `ELEVATED` / `HIGH_RISK` verdict with a 0–100 risk score and explained findings.

## Why an MCP server?

An LLM can reason about an IP, but it **cannot run live DNS, DNSBL or reverse-DNS lookups by itself**. ip-doctor does exactly that on demand — the moat is the live network access, not the reasoning.

## What it returns

| Signal | Source (key-less) |
| --- | --- |
| 🌍 Geolocation (RIR country) + ASN + organisation + BGP prefix | [Team Cymru](https://www.team-cymru.com/ip-asn-mapping) DNS IP-to-ASN |
| 🏷️ Network **type** — datacenter/hosting, VPN/proxy, Tor exit, mobile/carrier, residential ISP | deduced from ASN org + PTR + Tor list |
| 🔁 Reverse DNS (PTR) | `node:dns` reverse |
| 🚫 DNS blocklist (DNSBL) membership | DroneBL, blocklist.de, s5h, SORBS, UCEPROTECT, Barracuda, Spamhaus ZEN |
| 🧅 Tor exit node | Tor DNS exit list (`dnsel.torproject.org`) |
| 📊 0–100 abuse/risk score + verdict | derived from the above |

**Honesty:** geolocation is the **coarse RIR-allocation country**, not city-level GeoIP. The network **type** is a **deduction** from org/PTR signals, not an authoritative paid label. Blocklist zones that don't answer from a public resolver are reported as *inconclusive*, never silently "clean".

## Use it as an MCP server (free)

```json
{
  "mcpServers": {
    "ip-doctor": { "command": "npx", "args": ["-y", "ip-doctor-mcp"] }
  }
}
```

Tools:

- **`check_ip`** — `{ target: "8.8.8.8" | "example.com", deep?: boolean }`
- **`check_many`** — `{ targets: ["1.1.1.1", "evil.example", ...] }`

Or connect over HTTP at `POST /mcp` (stateless JSON-RPC).

## Use it as an HTTP API

Free tier (rate-limited, 40/h/IP):

```
GET https://ip-doctor.vercel.app/check?target=8.8.8.8
GET https://ip-doctor.vercel.app/check?target=example.com&deep=true
GET https://ip-doctor.vercel.app/check_many?targets=1.1.1.1,8.8.8.8,9.9.9.9
```

Pay-per-call (x402, **$0.02 USDC** on Base, DEEP tier — more blocklists + listing reasons, no rate limit):

```
GET https://ip-doctor.vercel.app/pro/check?target=<ip|domain>
GET https://ip-doctor.vercel.app/pro/check_many?targets=...
```

Your agent's x402-aware HTTP client pays automatically on the `402` challenge. The server holds **no private key** — `payTo` is a public receiving address only.

## Typical uses

- Vet inbound traffic / API callers (datacenter or Tor → step-up auth).
- Validate sign-ups & registrations (block known-abusive or proxy IPs).
- Moderate user-supplied IPs/domains in a pipeline.
- Enrich logs with ASN/org/type/blocklist context.

## Local dev

```bash
npm install
npm run build
npm run test:engine     # live DNS smoke tests
npm run dev:http        # local HTTP server on :8080 (payments OFF by default unless env set)
npm run dev:mcp         # stdio MCP server
```

## Notes

- Read-only. No code is executed; nothing is written. All lookups are DNS/DNSBL/reverse-DNS.
- Private/reserved addresses (RFC1918, loopback, CGNAT, link-local) are detected and skipped — no meaningless public lookups.
- IPv6 is supported for ASN/PTR/geo; most DNSBLs are IPv4-only and are reported as not-applicable for IPv6.

MIT licensed. Source: https://github.com/Baneado98/ip-doctor