mcp-server-ipinfo

IP Geolocation MCP Server

A Model Context Protocol server that exposes the ipinfo.io API to AI agents. Geolocate IPv4 and IPv6 addresses, identify ISPs and ASNs, detect VPN/proxy/Tor exit nodes, and generate interactive maps for sets of IPs.

Installation

Sign up for a free IPInfo API token at if you don't have one. The server runs with no token (free Lite tier — country and ASN basics) but most fields require a token.

Claude Desktop (one-click bundle)

Download the `.mcpb` bundle from the latest release and open it to install in Claude Desktop. You can set your `IPINFO_API_TOKEN` (and optional cache tuning) in the install dialog; leave the token blank to run in the free Lite tier. The bundle launches the server with `uv`, so `uv` must be installed and on your system `PATH` (GUI apps don't inherit your shell's `PATH`).

Other MCP clients

Most MCP clients accept the following values:

Development Version

To run the latest from `main`:

Tools

• `ipinfo_lookup_my_ip()` — Geolocate the calling client's own IP. Takes no arguments. On stdio transports the result reflects this server's outbound IP, not the end user's.
• `ipinfo_lookup_ips(ips, detail="summary")` — Geolocate one or more specified IPs. Defaults to `detail="summary"`, which omits heavy nested blocks (continent, flags, currency, abuse, domains) for batch token savings; pass `detail="full"` for every field. Capped at 500,000 IPs per call. Invalid or special-use addresses (private, loopback, etc.) are filtered with `ctx.warning()` and excluded from the result list, as are IPs that fail upstream — match returned `IPDetails.ip` values back to your input to detect what was dropped. If every attempted lookup fails, a temporary `api_error` is raised.
• `ipinfo_summarize_ips(ips, group_by=("country", "asn"), top_n=50)` — Geolocate and aggregate a batch into fixed-size counts and percentages by country, continent, ASN, and/or privacy flags. Use this for large log-analysis tasks where per-IP records would waste context. Returns mapped, skipped, and failed counts plus capped top-N groups.
• `ipinfo_check_residential_proxy(ip)` — Check whether an IP is a known residential-proxy exit node. Tagged `enterprise` — requires the IPInfo residential-proxy add-on.
• `ipinfo_generate_map_url(ips)` — Build an interactive ipinfo.io map for a set of IPs. Returns a `MapResult` with the URL, the count that made the map, the IPs filtered out (with reasons, capped at 100), and a `truncated` flag.

Plan tiers

Errors

Every tool raises a `ToolError` whose message is a JSON-encoded envelope with a stable `code` (`invalid_ip_address`, `special_ip_unsupported`, `no_valid_ips`, `too_many_ips`, `auth_invalid`, `auth_insufficient_scope`, `quota_exceeded`, `timeout`, `api_error`, `unknown_error`), a `temporary` flag, optional `retry_after_ms`, a `repair` hint, and a `request_id` correlation id. Agents should parse the message as JSON and branch on `code`. Each tool also advertises the subset of codes it can raise via `meta.error_codes`, so you can see the branch set from tool introspection.

Configuration

Environment Variables

License

MIT License — see LICENSE. Release history in CHANGELOG.md.

Disclaimer

This project is not affiliated with IPInfo.