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/

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.

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.

ipinfo_check_privacy

Checks whether IP addresses use VPN, proxy, relay, or Tor. Also includes flags for anycast, hosting, mobile, and satellite networks.

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

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 is limited to 1000.
• Requesting a page beyond available data returns empty results (not a hard error).

Error Codes and Recovery Actions

Notes

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