briandconnelly/mcp-server-ipinfo

PyPI CI License: MIT

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 https://ipinfo.io/signup 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:

Field	Value
Command	uvx
Arguments	mcp-server-ipinfo
Environment	IPINFO_API_TOKEN = <YOUR TOKEN>

Development Version

To run the latest from main:

Field	Value
Command	uvx
Arguments	--from, git+https://github.com/briandconnelly/mcp-server-ipinfo, mcp-server-ipinfo
Environment	IPINFO_API_TOKEN = <YOUR TOKEN>

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

Tier	Fields available
Free Lite (no token)	country, country_code, continent, ASN basics
Core	full geolocation, ASN details, privacy/VPN/proxy/Tor/hosting flags
Plus	adds carrier and company data
Enterprise	adds domains and abuse contacts
Residential-proxy add-on	enables ipinfo_check_residential_proxy. Sold separately on top of Enterprise; not included by default.

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

Variable	Description	Default
IPINFO_API_TOKEN	IPInfo API token. Without it the server runs in free Lite mode.	unset (Lite)
IPINFO_CACHE_TTL	Per-IP cache TTL in seconds. Cached results retain their original ts_retrieved timestamp.	3600
IPINFO_CACHE_SIZE	Maximum cache entries before oldest-first eviction.	4096

License

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

Disclaimer

This project is not affiliated with IPInfo.