ipinfo-mcp-server 0.2.0

IPinfo MCP Server

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.

For the full guide, see the official documentation.

Installation

All tools require an IPinfo API token. Get a free one at ipinfo.io/signup.

Hosted server

Point your MCP client at https://mcp.ipinfo.io/ (Streamable HTTP) and send your token as a bearer credential:

Authorization: Bearer <your-ipinfo-token>

Local server (PyPI)

The server is published on PyPI as ipinfo-mcp-server and runs over stdio. With uv installed, add it to your MCP client configuration:

{
  "mcpServers": {
    "ipinfo": {
      "command": "uvx",
      "args": ["ipinfo-mcp-server"],
      "env": {
        "IPINFO_TOKEN": "<your-ipinfo-token>"
      }
    }
  }
}

Claude Desktop extension

Download mcp.mcpb from the latest GitHub release and open it with Claude Desktop. You'll be asked for your API token during installation.

MCP Registry

The server is listed in the MCP Registry as io.github.ipinfo/mcp.

Tools

Tool	Description	Plan requirement
ipinfo_lookup	Full IP data: geolocation, network, and metadata	Any; detailed: true needs Core/Plus
ipinfo_geolocate	Geographic location	Any; detailed: true needs Core/Plus
ipinfo_asn	Autonomous system (network ownership)	Any; detailed: true needs Core/Plus
ipinfo_check_privacy	VPN, proxy, relay, Tor, hosting, anycast, mobile, satellite flags	Paid plan
ipinfo_check_residential_proxy	Residential proxy detection	Residential Proxy access
ipinfo_quota	API usage and remaining quota	Any

Tools that lack access for the token's plan return an ACCESS_DENIED error.

Common parameters

All tools except ipinfo_quota take a list of IPs and are paginated:

Parameter	Type	Default	Description
ips	string[]	required	Public IPv4 or IPv6 addresses. Private, loopback, reserved, multicast, and bogon addresses are rejected and reported in validation_errors.
page	integer	1	1-based page of the result set. Values below 1 are clamped to 1.
page_size	integer	25	IPs resolved per page, up to 1000. Only IPs on the requested page are fetched, so smaller pages consume less quota per call.

ipinfo_lookup, ipinfo_geolocate, and ipinfo_asn also take:

Parameter	Type	Default	Description
detailed	boolean	false	false queries the Lite endpoint. true queries the full lookup endpoint, which returns more fields.

Common output

IP-based tools return:

Field	Description
results	Object keyed by IP with the tool-specific data below.
errors	Object keyed by IP for IPs the API returned an error for. These IPs are left out of results.
validation_errors	Object keyed by input for values that aren't valid public IPs. Only present when there are any.
_pagination	total_results, page, page_size, total_pages, has_next, has_previous.
_meta	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.

ipinfo_lookup

Returns the raw IPinfo API response for each IP.

• detailed: false (Lite): ip, asn, as_name, as_domain, country, country_code, continent, continent_code.
• 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.

ipinfo_check_privacy

Returns, per IP: ip, is_anonymous, anonymous (is_proxy, is_relay, is_tor, is_vpn), is_anycast, is_hosting, is_mobile, is_satellite.

ipinfo_check_residential_proxy

Returns, per IP: ip and is_residential_proxy. For residential proxies, also service (proxy service name), last_seen (date), and percent_days_seen.

ipinfo_quota

Takes no parameters. Returns token (omitted when connected with OAuth), requests (day, month, limit, remaining), and per-feature quotas under features.

Configuration

The server is configured through environment variables:

Variable	Default	Description
IPINFO_TOKEN		API token (stdio transport; over HTTP the token comes from the request)
IPINFO_API_BASE_URL	https://api.ipinfo.io	Base URL for api.ipinfo.io endpoints
IPINFO_LEGACY_BASE_URL	https://ipinfo.io	Base URL for legacy ipinfo.io endpoints (e.g. /me)
IPINFO_CACHE_TTL	3600	Seconds a cached IP result stays fresh
IPINFO_TRANSPORT	stdio	Transport type (stdio or http)
HOST	0.0.0.0	HTTP host (only for http transport)
PORT	8000	HTTP port (only for http transport)
IPINFO_OAUTH_ISSUER		OAuth issuer whose access tokens are accepted; OAuth is off when unset
IPINFO_MCP_RESOURCE_URL		Public URL of this server, required with IPINFO_OAUTH_ISSUER
IPINFO_OAUTH_JWKS_URI	<issuer>/.well-known/jwks.json	Where the issuer publishes its signing keys

With the http transport, each request authenticates with its own Authorization: Bearer <token> header.

Setting IPINFO_OAUTH_ISSUER turns on OAuth for the http transport. The server then advertises the issuer at /.well-known/oauth-protected-resource, answers requests without a valid credential with 401 Unauthorized, and verifies access tokens against the issuer's signing keys. A verified access token is sent to the IPinfo API in place of an API token. API tokens keep working as before.

Feedback

• Bugs and feature requests: open an issue on GitHub Issues.
• Security vulnerabilities: don't open a public issue; follow the security policy.
• Questions about your IPinfo account or plan: contact support@ipinfo.io.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the workflow and the requirements a change has to meet.

Development

Prerequisites

• Python 3.14+
• uv

Setup

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.

# 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

# 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.

Type checking

uv run pyright

Linting

uv run ruff check .
uv run ruff format .