Back to Browse

Mcp MCP Server

by Ipinfo
Developer ToolsLow Risk8.5MCP RegistryLocalRemote
Free

Server data from the Official MCP Registry

Official IPinfo MCP Server - IP intelligence tools for AI assistants

About

Official IPinfo MCP Server - IP intelligence tools for AI assistants

Remote endpoints: streamable-http: https://mcp.ipinfo.io/

Security Report

8.5
Low Risk8.5Low Risk

Valid MCP server (0 strong, 3 medium validity signals). 3 known CVEs in dependencies Imported from the Official MCP Registry. 1 finding(s) downgraded by scanner intelligence.

Endpoint verified · Requires authentication · 5 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

env_vars

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

What You'll Need

Set these up before or after installing:

Your IPinfo API token. Get a free one at https://ipinfo.io/signupRequired

Environment variable: IPINFO_TOKEN

How to Install & Connect

Available as Local & Remote

This plugin can run on your machine or connect to a hosted endpoint. during install.

Documentation

View on GitHub

From the project's GitHub README.

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.

OpenSSF Scorecard OpenSSF Best Practices

Installation

You need an IPinfo account. Sign up for free at ipinfo.io/signup.

Hosted server

Point your MCP client at https://mcp.ipinfo.io/ (Streamable HTTP). The first time it connects, it asks you to sign in with your IPinfo account through OAuth.

Local server (PyPI)

The server is published on PyPI as ipinfo-mcp-server and runs over stdio, authenticating with your API token. 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.

Gemini CLI extension

Install the extension, which connects Gemini CLI to the hosted server:

gemini extensions install https://github.com/ipinfo/mcp

Then run /mcp auth ipinfo in Gemini CLI to sign in with your IPinfo account.

MCP Registry

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

The server is also listed on LightNow.

Tools

ToolDescriptionPlan requirement
ipinfo_lookupFull IP data: geolocation, network, and metadataAny; detailed: true needs Core/Plus
ipinfo_geolocateGeographic locationAny; detailed: true needs Core/Plus
ipinfo_asnAutonomous system (network ownership)Any; detailed: true needs Core/Plus
ipinfo_check_privacyVPN, proxy, relay, Tor, hosting, anycast, mobile, satellite flagsPaid plan
ipinfo_check_residential_proxyResidential proxy detectionResidential Proxy access
ipinfo_quotaAPI usage and remaining quotaAny
ipinfo_lite_lookupLite IP data, for agents without an accountNone; only offered to AAuth agents

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:

ParameterTypeDefaultDescription
ipsstring[]requiredPublic IPv4 or IPv6 addresses. Private, loopback, reserved, multicast, and bogon addresses are rejected and reported in validation_errors.
pageinteger11-based page of the result set. Values below 1 are clamped to 1.
page_sizeinteger25IPs 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:

ParameterTypeDefaultDescription
detailedbooleanfalsefalse queries the Lite endpoint. true queries the full lookup endpoint, which returns more fields.

Common output

IP-based tools return:

FieldDescription
resultsObject keyed by IP with the tool-specific data below.
errorsObject keyed by IP for IPs the API returned an error for. These IPs are left out of results.
validation_errorsObject keyed by input for values that aren't valid public IPs. Only present when there are any.
_paginationtotal_results, page, page_size, total_pages, has_next, has_previous.
_metaapi_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.

ipinfo_lite_lookup

Only offered to agents that sign their requests with AAuth, who get it in place of the tools above. Calling it needs a person token, which names the person the agent acts for. Takes the common parameters and returns the Lite data for each IP: ip, asn, as_name, as_domain, country, country_code, continent, continent_code. When the person reaches their daily limit for lookups without an account, it returns a RATE_LIMITED error.

Configuration

The server is configured through environment variables:

VariableDefaultDescription
IPINFO_TOKENAPI token (stdio transport; over HTTP the token comes from the request)
IPINFO_API_BASE_URLhttps://api.ipinfo.ioBase URL for api.ipinfo.io endpoints
IPINFO_LEGACY_BASE_URLhttps://ipinfo.ioBase URL for legacy ipinfo.io endpoints (e.g. /me)
IPINFO_CACHE_TTL3600Seconds a cached IP result stays fresh
IPINFO_TRANSPORTstdioTransport type (stdio or http)
HOST0.0.0.0HTTP host (only for http transport)
PORT8000HTTP port (only for http transport)
IPINFO_OAUTH_ISSUEROAuth issuer whose access tokens are accepted; OAuth is off when unset
IPINFO_MCP_RESOURCE_URLPublic URL of this server, required with IPINFO_OAUTH_ISSUER
IPINFO_OAUTH_JWKS_URI<issuer>/.well-known/jwks.jsonWhere the issuer publishes its signing keys
IPINFO_OPENAI_APPS_CHALLENGEToken served at /.well-known/openai-apps-challenge for OpenAI's domain verification
IPINFO_AAUTH_PROVIDER_KEYEd25519 private key, PEM encoded, for AAuth; AAuth is off when unset
IPINFO_AAUTH_ISSUERPublic URL of this server for AAuth, required with the key
IPINFO_AAUTH_PERSON_SERVERSComma separated AAuth person servers whose person tokens are accepted, required with the key

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.

Setting IPINFO_AAUTH_PROVIDER_KEY turns on AAuth for the http transport, so people without an IPinfo account can use ipinfo_lite_lookup through agents that sign their requests with AAuth. Generate the key with openssl genpkey -algorithm ed25519, and give every replica the same one. IPINFO_AAUTH_ISSUER must be the server's public URL: https, no port, path, or trailing slash. When IPINFO_MCP_RESOURCE_URL is set too, its scheme and host must match IPINFO_AAUTH_ISSUER, or the server won't start. IPINFO_AAUTH_PERSON_SERVERS lists the AAuth person servers whose person tokens are accepted, written the same way, for example https://person.hello.coop. With AAuth on, the server also serves:

  • /aauth, the MCP endpoint for AAuth agents, whose only tool is ipinfo_lite_lookup. Listing its tools needs no signature. Calling one needs an AAuth signature presenting a person token from one of IPINFO_AAUTH_PERSON_SERVERS, issued for IPINFO_AAUTH_ISSUER; any other call is answered with 401 and AAuth-Requirement: requirement=person-token. When IPINFO_MCP_RESOURCE_URL is set, only signatures made for that host are accepted.
  • /.well-known/aauth-resource.json, which points agents at /aauth. It names IPINFO_AAUTH_ISSUER, which person tokens must be issued for.
  • /.well-known/aauth-agent.json and /.well-known/aauth-jwks.json, the documents of the server's own AAuth agent, aauth:ipinfo-mcp@<issuer host>.

The main endpoint is unaffected.

Feedback

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 .

Reviews

No reviews yet

Be the first to review this server!