mcp-server-ipinfo is a Model Context Protocol (MCP) server that exposes the ipinfo.io API to AI agents. Its purpose is to enable AI agents to perform geolocation and network information lookups for IP addresses.
Main capabilities
- Geolocate IPv4 and IPv6 addresses.
- Identify ISP and ASN.
- Detect VPN, proxy, and Tor exit nodes.
- Generate interactive maps for multiple sets of IPs.
- Provides the following MCP tools:
- ipinfo_lookup_my_ip(): Locates the calling client's own IP, with no parameters. Under stdio transport, the result reflects the server's outbound IP, not the end user's IP.
- ipinfo_lookup_ips(ips, detail="summary"): Locates one or more specified IPs. By default detail="summary", omitting nested blocks such as continent, flags, currency, abuse, and domains to save tokens in batch processing; pass detail="full" to return all fields. Up to 500,000 IPs per call. Invalid or special-purpose addresses (private, loopback, etc.) are filtered out and indicated with ctx.warning(), and do not appear in the results list; IPs that fail upstream are also excluded; the returned IPDetails.ip value must be matched against the input to detect dropped entries. If all queries fail, a temporary api_error is thrown.
- ipinfo_summarize_ips(ips, group_by=("country", "asn"), top_n=50): Geolocates a batch of IPs and aggregates them into fixed-size counts and percentages by country, continent, ASN, and/or privacy flags. Suitable for large log analysis tasks where per-IP records would waste context. Returns mapped, skipped, and failed counts, as well as truncated top-N groups.
- ipinfo_check_residential_proxy(ip): Checks whether an IP is a known residential proxy exit node. Marked as an enterprise feature, requires the IPinfo residential-proxy add-on.
- ipinfo_generate_map_url(ips): Builds an interactive ipinfo.io map for a set of IPs. Returns a MapResult containing the URL, the number of IPs used to generate the map, the IPs that were filtered out (with reasons, up to 100), and a truncation flag.
Error handling: Each tool throws a ToolError whose message is a JSON-encoded envelope containing 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, an optional retry_after_ms, a remediation hint, and a request_id correlation ID. Agents should parse the message as JSON and branch on the code. Each tool also declares via meta.error_codes the subset of codes it may throw, so the branching set can be viewed through tool introspection.
How to use
- Register a free IPinfo API token:https://ipinfo.io/signup。若没有令牌，服务器以免费 Runs at the Lite tier (basic country and ASN information), but most fields require a token.
- Claude Desktop (one-click package): Download the .mcpb package from the latest release and open it to install into Claude Desktop. IPINFO_API_TOKEN (and optional cache tuning) can be set in the installation dialog; if the token is left blank, it runs at the free Lite tier. The package uses uv to start the server, so uv must be installed and on the system PATH (GUI applications do not inherit the shell's PATH).
- Other MCP clients: Most MCP clients accept the configuration values above.
- Development version: Run the latest code from main.
Use cases
- Log analysis: Aggregate statistics over large numbers of IPs, saving context.
- Batch IP geolocation and network information queries.
- Identify VPNs, proxies, and Tor exit nodes.
- Generate interactive maps of IP sets.
Limitations
- Without a token, only the free Lite tier is supported (basic country and ASN information); most fields require an API token.
- Residential proxy checks require the enterprise-level residential-proxy add-on.
- ipinfo_lookup_ips supports up to 500,000 IPs per call.
- Under the stdio transport, the result of ipinfo_lookup_my_ip reflects the server's outbound IP, not the end user's IP.
- This project is not affiliated with IPInfo.
License: MIT License, see LICENSE for details. For release history, see CHANGELOG.md.
