Mcp Server Ipinfo
🐍 ☁️ - IP address geolocation and network information using IPInfo API
Quick Install
{
"mcpServers": {
"briandconnelly-mcp-server-ipinfo": {
"command": "npx",
"args": [
"-y",
"briandconnelly-mcp-server-ipinfo"
]
}
}
}Using an AI coding agent (Claude Code, Cursor, etc.)? Copy a ready-made prompt that tells it to fetch the setup instructions and install this server for you.
Documentation Overview
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 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 todetail="summary", which omits heavy nested blocks (continent, flags, currency, abuse, domains) for batch token savings; passdetail="full"for every field. Capped at 500,000 IPs per call. Invalid or special-use addresses (private, loopback, etc.) are filtered withctx.warning()and excluded from the result list, as are IPs that fail upstream — match returnedIPDetails.ipvalues back to your input to detect what was dropped. If every attempted lookup fails, a temporaryapi_erroris 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. Taggedenterprise— requires the IPInfo residential-proxy add-on.ipinfo_generate_map_url(ips)— Build an interactive ipinfo.io map for a set of IPs. Returns aMapResultwith the URL, the count that made the map, the IPs filtered out (with reasons, capped at 100), and atruncatedflag.
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.