Official IPinfo MCP Server - IP intelligence tools for AI assistants
io.github.ipinfo/mcp MCP Server
The io.github.ipinfo/mcp server provides IP intelligence tools for AI assistants, described as the “Official IPinfo MCP Server.” It targets IPinfo API use cases for Residential Proxy, Lite, Core, and Plus bundles and includes setup guidance for running the server.
🛠️ Key Features
Official IPinfo MCP Server
IP intelligence tools for AI assistants
Supports IPinfo API bundles: Residential Proxy, Lite, Core, Plus
Reported toolCount: 6
🚀 Use Cases
Use IPinfo API intelligence for AI assistant workflows
Integrate IP intelligence tied to specific IPinfo bundle offerings (Residential Proxy, Lite, Core, Plus)
⚡ Developer Benefits
GitHub-referenced server for IPinfo API integration
Includes development prerequisites and environment setup steps
⚠️ Limitations
Documentation excerpt provided does not describe individual tools, parameters, or runtime behavior beyond bundle scope
Development
Prerequisites: Python 3.14+ and uv
Setup: uv sync --dev, copy .env.example to .env, add an IPinfo token to .env
Captured live from the server via tools/list.
ipinfo_lookup
Look up geolocation, network, and metadata for one or more IP addresses.
By default queries the IPinfo Lite endpoint, which returns country, continent, and ASN info.
Set detailed=True to query the full lookup endpoint, which adds city-level geolocation,
privacy flags (VPN, proxy, Tor, hosting, anycast), and richer AS data.
Results are paginated. Use page and page_size to control which slice is returned.
If the API reports an error for specific IPs, those IPs are listed in errors
with the reason and left out of results.
Results are cached in memory for the session, so repeat lookups of the same IP
are served from cache without consuming API quota. You do not need to maintain
your own cache or deduplicate IPs before calling this tool. The _meta field
reports api_calls_made and from_cache counts.
Parameters4
ips
array
required
Public IP addresses to query, IPv4 or IPv6, e.g. ["8.8.8.8", "2001:4860:4860::8888"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.
detailed
boolean
optional
Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which returns country, continent, and basic ASN. Set to true to use the full lookup endpoint, which also returns city-level geolocation, privacy flags (VPN, proxy, Tor, hosting, anycast), and richer AS data; it requires a token whose plan includes that data, otherwise the call fails with ACCESS_DENIED.
page
integer
optional
Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.
page_size
integer
optional
How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.
Raw schema
{
"type": "object",
"properties": {
"ips": {
"description": "Public IP addresses to query, IPv4 or IPv6, e.g. [\"8.8.8.8\", \"2001:4860:4860::8888\"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.",
"items": {
"type": "string"
},
"type": "array"
},
"detailed": {
"default": false,
"description": "Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which returns country, continent, and basic ASN. Set to true to use the full lookup endpoint, which also returns city-level geolocation, privacy flags (VPN, proxy, Tor, hosting, anycast), and richer AS data; it requires a token whose plan includes that data, otherwise the call fails with ACCESS_DENIED.",
"type": "boolean"
},
"page": {
"default": 1,
"description": "Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.",
"type": "integer"
},
"page_size": {
"default": 25,
"description": "How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.",
"type": "integer"
}
},
"required": [
"ips"
],
"additionalProperties": false
}
ipinfo_check_privacy
Check whether IP addresses are using privacy or anonymity services.
Returns privacy flags for each IP: whether it is anonymous, using a VPN, proxy,
relay, or Tor, and whether it is an anycast, hosting, mobile, or satellite address.
Requires a paid API token. Results are paginated.
If the API reports an error for specific IPs, those IPs are listed in errors
with the reason and left out of results. Do not treat a missing result as
"no privacy services detected": check errors.
Results are cached in memory for the session, so repeat checks of the same IP
are served from cache without consuming API quota. You do not need to maintain
your own cache or deduplicate IPs before calling this tool. The _meta field
reports api_calls_made and from_cache counts.
Parameters3
ips
array
required
Public IP addresses to query, IPv4 or IPv6, e.g. ["8.8.8.8", "2001:4860:4860::8888"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.
page
integer
optional
Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.
page_size
integer
optional
How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.
Raw schema
{
"type": "object",
"properties": {
"ips": {
"description": "Public IP addresses to query, IPv4 or IPv6, e.g. [\"8.8.8.8\", \"2001:4860:4860::8888\"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.",
"items": {
"type": "string"
},
"type": "array"
},
"page": {
"default": 1,
"description": "Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.",
"type": "integer"
},
"page_size": {
"default": 25,
"description": "How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.",
"type": "integer"
}
},
"required": [
"ips"
],
"additionalProperties": false
}
ipinfo_check_residential_proxy
Check whether IP addresses are known residential proxies.
Returns whether each IP is a residential proxy and, if so, the proxy service name,
the date it was last seen, and the percentage of days the IP was observed as a proxy.
Requires a paid API token with residential proxy access. Results are paginated.
If the API reports an error for specific IPs, those IPs are listed in errors
with the reason and left out of results. Do not treat a missing result as
"not a residential proxy": check errors.
Results are cached in memory for the session, so repeat checks of the same IP
are served from cache without consuming API quota. You do not need to maintain
your own cache or deduplicate IPs before calling this tool. The _meta field
reports api_calls_made and from_cache counts.
Parameters3
ips
array
required
Public IP addresses to query, IPv4 or IPv6, e.g. ["8.8.8.8", "2001:4860:4860::8888"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.
page
integer
optional
Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.
page_size
integer
optional
How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.
Raw schema
{
"type": "object",
"properties": {
"ips": {
"description": "Public IP addresses to query, IPv4 or IPv6, e.g. [\"8.8.8.8\", \"2001:4860:4860::8888\"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.",
"items": {
"type": "string"
},
"type": "array"
},
"page": {
"default": 1,
"description": "Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.",
"type": "integer"
},
"page_size": {
"default": 25,
"description": "How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.",
"type": "integer"
}
},
"required": [
"ips"
],
"additionalProperties": false
}
ipinfo_geolocate
Get geographic location data for one or more IP addresses.
By default queries the IPinfo Lite endpoint, which returns country and continent.
Set detailed=True to query the full lookup endpoint, which adds city, region,
coordinates, timezone, and postal code.
Results are paginated.
If the API reports an error for specific IPs, those IPs are listed in errors
with the reason and left out of results.
Results are cached in memory for the session, so repeat lookups of the same IP
are served from cache without consuming API quota. You do not need to maintain
your own cache or deduplicate IPs before calling this tool. The _meta field
reports api_calls_made and from_cache counts.
Parameters4
ips
array
required
Public IP addresses to query, IPv4 or IPv6, e.g. ["8.8.8.8", "2001:4860:4860::8888"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.
detailed
boolean
optional
Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which returns country and continent only. Set to true to use the full lookup endpoint, which also returns city, region, latitude and longitude, timezone, and postal code; it requires a token whose plan includes that data, otherwise the call fails with ACCESS_DENIED.
page
integer
optional
Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.
page_size
integer
optional
How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.
Raw schema
{
"type": "object",
"properties": {
"ips": {
"description": "Public IP addresses to query, IPv4 or IPv6, e.g. [\"8.8.8.8\", \"2001:4860:4860::8888\"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.",
"items": {
"type": "string"
},
"type": "array"
},
"detailed": {
"default": false,
"description": "Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which returns country and continent only. Set to true to use the full lookup endpoint, which also returns city, region, latitude and longitude, timezone, and postal code; it requires a token whose plan includes that data, otherwise the call fails with ACCESS_DENIED.",
"type": "boolean"
},
"page": {
"default": 1,
"description": "Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.",
"type": "integer"
},
"page_size": {
"default": 25,
"description": "How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.",
"type": "integer"
}
},
"required": [
"ips"
],
"additionalProperties": false
}
ipinfo_asn
Get autonomous system (network ownership) information for IP addresses.
By default queries the IPinfo Lite endpoint, which returns ASN, name, and domain.
Set detailed=True to query the full lookup endpoint, which also includes the network type
(e.g. isp, hosting, business, education).
Results are paginated.
If the API reports an error for specific IPs, those IPs are listed in errors
with the reason and left out of results.
Results are cached in memory for the session, so repeat lookups of the same IP
are served from cache without consuming API quota. You do not need to maintain
your own cache or deduplicate IPs before calling this tool. The _meta field
reports api_calls_made and from_cache counts.
Parameters4
ips
array
required
Public IP addresses to query, IPv4 or IPv6, e.g. ["8.8.8.8", "2001:4860:4860::8888"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.
detailed
boolean
optional
Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which returns the ASN, name, and domain. Set to true to use the full lookup endpoint, which also returns the network type (isp, hosting, business, education) and when the AS record last changed; it requires a token whose plan includes that data, otherwise the call fails with ACCESS_DENIED.
page
integer
optional
Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.
page_size
integer
optional
How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.
Raw schema
{
"type": "object",
"properties": {
"ips": {
"description": "Public IP addresses to query, IPv4 or IPv6, e.g. [\"8.8.8.8\", \"2001:4860:4860::8888\"]. Private, loopback, reserved, multicast, and bogon addresses are rejected: they are reported under validation_errors and left out of results.",
"items": {
"type": "string"
},
"type": "array"
},
"detailed": {
"default": false,
"description": "Which IPinfo endpoint to query. Leave false to use the Lite endpoint, which returns the ASN, name, and domain. Set to true to use the full lookup endpoint, which also returns the network type (isp, hosting, business, education) and when the AS record last changed; it requires a token whose plan includes that data, otherwise the call fails with ACCESS_DENIED.",
"type": "boolean"
},
"page": {
"default": 1,
"description": "Page of the result set to return, 1-based. Values below 1 are clamped to 1, and a page past the last one returns no results.",
"type": "integer"
},
"page_size": {
"default": 25,
"description": "How many IPs to resolve and return per page. Clamped to a maximum of 1000, the API batch limit. Only the IPs on the requested page are fetched, so a smaller page size consumes less quota per call.",
"type": "integer"
}
},
"required": [
"ips"
],
"additionalProperties": false
}
ipinfo_quota
Check your IPinfo API usage and remaining quota.
Returns daily and monthly request counts, the plan limit,
and how many requests remain.
The official IPinfo MCP Server lets AI assistants such as Claude answer questions about IP addresses. Ask where an IP is located, which company or network it belongs to, or whether it's a VPN, proxy, Tor exit node, or residential proxy, and the assistant looks it up with IPinfo data.
It implements the Model Context Protocol (MCP), the open standard AI assistants use to connect to external tools, so it works with any MCP-compatible client. It supports the IPinfo Lite, Core, Plus, and Residential Proxy plans.
api_calls_made and from_cache. Results are cached in memory, so repeat lookups don't consume API quota.
If the whole request fails (for example a missing or invalid token), the tool returns an error object instead, with code (ACCESS_DENIED, RATE_LIMITED, INVALID_TOKEN, NO_TOKEN, API_ERROR, or UNKNOWN), message, and suggestion.
detailed: true (full lookup): ip, hostname, geo (city, region, country, continent, coordinates, timezone, postal code), as (ASN, name, domain, type), anonymous (proxy, relay, Tor, VPN), mobile, and the is_anonymous, is_anycast, is_hosting, is_mobile, is_satellite flags. Some fields are only available on Plus.
ipinfo_geolocate
Returns, per IP: ip, country, country_code, continent, continent_code. With detailed: true, also city, region, region_code, latitude, longitude, timezone, postal_code.
ipinfo_asn
Returns, per IP: ip, asn, name, domain. With detailed: true, also type (isp, hosting, business, education) and last_changed.
uv sync --dev
cp .env.example .env# Add your IPinfo token to .env
Running the server
The server supports two transports: stdio (default) and HTTP.
bash
# stdio (default, used by MCP clients)
uv run ipinfo-mcp-server
# HTTP
IPINFO_TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run ipinfo-mcp-server
Tests
bash
# All tests
uv run pytest
# Integration tests (requires IPINFO_TOKEN)
uv run pytest tests/integration/
Integration tests hit the real IPinfo API and validate response structure only (no exact value assertions). They require IPINFO_TOKEN to be set and are skipped otherwise.