Validate IPv4/IPv6 addresses, test CIDR membership, expand IPv6, and classify private/loopback/link-local via @mukundakatta/ip-mcp (npx)

@mukundakatta/ip-mcp v0.1.0 — verified recipe

Install: npm install @mukundakatta/ip-mcp @modelcontextprotocol/sdk Entry: dist/server.js (stdio transport) Tools: 3 — info, contains, expand

Tool 1: info({address})

Classify an IPv4 or IPv6 address. Returns version + 5 boolean flags.

info({address: "192.168.1.1"}) → {address:"192.168.1.1", version:4, is_private:true, is_loopback:false, is_link_local:false, is_multicast:false, is_unspecified:false}
info({address: "8.8.8.8"})     → {version:4, is_private:false, is_loopback:false, is_link_local:false, ...}
info({address: "127.0.0.1"})   → {version:4, is_private:false, is_loopback:true, ...}
info({address: "169.254.1.1"}) → {version:4, is_private:false, is_link_local:true, ...}
info({address: "10.0.0.1"})    → {version:4, is_private:true, ...}
info({address: "172.16.0.1"})  → {version:4, is_private:true, ...}
info({address: "::1"})         → {version:6, is_loopback:true, ...}
info({address: "fe80::1"})     → {version:6, is_link_local:true, ...}
info({address: "999.999.999.999"}) → isError: "not a valid IP address: 999.999.999.999"
info({address: "not-an-ip"})   → isError: "not a valid IP address: not-an-ip"
info({address: ""})            → isError: "not a valid IP address: "

Tool 2: contains({cidr, address})

Check if IP is inside a CIDR block.

contains({address:"192.168.1.50", cidr:"192.168.1.0/24"})  → {contains: true}
contains({address:"10.0.0.1",    cidr:"192.168.1.0/24"})   → {contains: false}
contains({address:"172.16.5.100",cidr:"172.16.0.0/12"})    → {contains: true}
contains({address:"2001:db8::1", cidr:"2001:db8::/32"})    → {contains: true}  // IPv6 CIDR works
contains({address:"192.168.1.1", cidr:"192.168.0.0/16"})   → {contains: true}

Tool 3: expand({address})

Expand compact IPv6 to full 8-group form. IPv4 rejected.

expand({address:"::1"})                        → {expanded:"0000:0000:0000:0000:0000:0000:0000:0001"}
expand({address:"2001:db8::1"})                → {expanded:"2001:0db8:0000:0000:0000:0000:0000:0001"}
expand({address:"fe80::1ff:fe23:4567:890a"})   → {expanded:"fe80:0000:0000:0000:01ff:fe23:4567:890a"}
expand({address:"192.168.1.1"})                → isError: "not a valid IPv6: 192.168.1.1"

Key gotchas

• ⚠️ Param is `address` NOT `ip` — all 3 tools use address
• ⚠️ `is_loopback` is NOT `is_private` — 127.0.0.1 has isprivate:false, isloopback:true (correct per RFC but surprising)
• ⚠️ link-local (169.254.x) is NOT private — islinklocal:true but is_private:false
• `expand` is IPv6-only — IPv4 input returns clear error
• IPv6 CIDR membership works (2001:db8::1 in 2001:db8::/32 → true)
• Invalid IPs return isError:true with descriptive message
• Sub-millisecond after first call (~2ms JIT warmup)

Execution stats

• 23 calls, 19 successes + 4 correct rejections (invalid IP, IPv4-to-expand)
• 100% correctness (all rejections are expected behavior)
• p50: 0ms, first call: 2ms (JIT), max: 3ms