IPinfo MCP Server

The IPinfo MCP Server gives AI assistants and MCP-compatible developer tools direct access to IP address intelligence from IPinfo. You can connect clients such as Claude Desktop, VS Code, Cursor, LM Studio, Gemini CLI, Claude Code, and Codex CLI to query geolocation, ASN, privacy, residential proxy, and quota data.

Point your MCP client to this URL:

https://mcp.ipinfo.io/

Quick Install

Visit https://mcp.ipinfo.io/ in a browser. Paste your IPinfo token into the token field and the page will generate ready-to-copy configurations for every supported client. For Claude Desktop, VS Code, Cursor, and LM Studio, one-click install buttons are also available on the landing page.

If you prefer manual setup, use the configurations in the next section.

Authentication

The MCP server reads the IPinfo API token from the Authorization: Bearer <IPINFO_TOKEN> header on each request. No server-side account or login is required, the token alone authenticates requests and determines which tools and fields are available based on your plan.

Get a free token at ipinfo.io/signup.

Client Setup

Paste your IPinfo token into the examples below to configure the server in your MCP client.

Code-Focused MCP Clients

{
  "servers": {
    "ipinfo": {
      "type": "http",
      "url": "https://mcp.ipinfo.io/",
      "headers": {
        "Authorization": "Bearer <IPINFO_TOKEN>"
      }
    }
  }
}

General MCP Clients

{
  "mcpServers": {
    "ipinfo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.ipinfo.io/",
        "--header",
        "Authorization: Bearer <IPINFO_TOKEN>"
      ]
    }
  }
}

Tools

Available Tools

The MCP server exposes the following IPinfo tools.

ipinfo_lookup

Geolocation, network, and metadata for IP addresses. Set detailed=true for city-level geolocation, privacy flags, and richer ASN data. The detailed=true mode requires a paid token.

ipinfo_geolocate

Geographic location data for one or more IP addresses. The free tier returns country and continent, while detailed=true adds city, region, coordinates, timezone, and postal code.

ipinfo_asn

Autonomous system and network ownership information, including ASN, organization name, and domain. Set detailed=true for network type such as ISP, hosting, business, or education, and last_changed metadata.

ipinfo_check_privacy

Checks whether IP addresses use VPN, proxy, relay, or Tor. Also includes flags for anycast, hosting, mobile, and satellite networks. With a Plus-tier token, the anonymous.name field returns the VPN provider name when available.

ipinfo_check_residential_proxy

Detects residential proxy usage and returns the proxy service name, last seen date, and observation frequency.

ipinfo_quota

Returns API usage and remaining quota, including daily and monthly counts, plan limits, and remaining requests.

Tool Selection Quick Guide

Use this mapping to choose the right tool for the user intent.

Usage Guidance

Response Format

Every paginated tool returns a consistent response shape with four sections: _pagination, _meta, results, and optionally validation_errors.

Example response from ipinfo_lookup:

{
  "_pagination": {
    "total_results": 2,
    "page": 1,
    "page_size": 25,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false
  },
  "_meta": {
    "api_calls_made": 1,
    "from_cache": 0
  },
  "results": {
    "8.8.8.8": {
      "ip": "8.8.8.8",
      "country": "United States",
      "country_code": "US",
      "continent": "North America",
      "continent_code": "NA",
      "asn": "AS15169",
      "as_name": "Google LLC",
      "as_domain": "google.com"
    },
    "1.1.1.1": {
      "ip": "1.1.1.1",
      "country": "Australia",
      "country_code": "AU",
      "continent": "Oceania",
      "continent_code": "OC",
      "asn": "AS13335",
      "as_name": "Cloudflare Inc.",
      "as_domain": "cloudflare.com"
    }
  },
  "validation_errors": {
    "192.168.1.1": "'192.168.1.1' is a private IP address. Only public IP addresses can be looked up."
  }
}

Successful results are keyed by IP in the results object. Invalid inputs appear in validation_errors instead of causing the whole request to fail.

On error, a tool returns a different shape:

{
  "error": true,
  "code": "ACCESS_DENIED",
  "message": "You don't have access to this feature.",
  "suggestion": "Tell the user they can get access by upgrading at /pricing"
}

Caching and Quota

The server maintains an in-memory cache for the lifetime of the MCP session. Repeat lookups of the same IP are served from cache and do not consume API quota. The cache is scoped by tool mode (lite, detailed, residential proxy) so a detailed lookup will not be served from a lite cache entry.

Each response includes a _meta object reporting api_calls_made (how many times the IPinfo API was called during this tool invocation) and from_cache (how many results were served from the session cache). Clients do not need to deduplicate input lists, the cache handles that automatically.

Prompting Best Practices

• Include the exact tool name in the prompt.
• Specify required output fields explicitly.
• If city-level output is needed, require detailed=true.
• When applicable, require validation_errors to be returned.
• For large inputs on paginated tools, require pagination completion (page_size<=1000 and iterate all pages).

Example template:

Use exactly <tool_name> for these IPs: [IPs].
Return fields: [field list].
When applicable, also return validation_errors and pagination metadata.
If error=true, map code to recovery action.

Prompt Scenario Table

Use this quick-reference table to improve prompt quality when working with AI assistants and the IPinfo MCP tools.

Response Handling Rules

When interpreting any tool response, use this order:

1. Check top-level error first.
2. Check _pagination to confirm result coverage.
3. Read results for successful IPs.
4. Read validation_errors for rejected IPs.

This prevents common misreads where empty results are treated as API failures.

Validation and Pagination Behavior

• Input supports mixed-quality IP lists.
• Valid public IPs are processed.
• Invalid/private/loopback/reserved/multicast/bogon IPs appear in validation_errors.
• A single response can contain both successful results and validation_errors.
• page_size defaults to 25 and is capped at 1000.
• The underlying batch endpoint processes up to 1000 IPs per API call.
• Requesting a page beyond available data returns empty results (not a hard error).

Error Codes and Recovery Actions

Top-level errors (when the whole request fails) use the following codes. For per-IP validation issues such as private or malformed addresses, inspect the validation_errors field in the response instead.

Notes

• The MCP server is powered by the IPinfo API.
• All examples above use bearer token authentication through the Authorization header.
• Support for manual setup details can vary slightly by client version.