Overview

This MCP (Model Context Protocol) server exposes IP2Location.io geolocation lookups as a FastMCP tool. Given an IPv4 or IPv6 address, the server queries IP2Location.io and returns structured geolocation, network, mobile, currency/language, and proxy/security details in JSON. It’s designed to integrate with MCP-capable clients (for example, Claude Desktop) so models can fetch authoritative IP information during a conversation or workflow.

Two usage tiers are supported: anonymous queries (no API key) are allowed but limited to about 1,000 requests per day; registering for a free IP2Location.io account and setting IP2LOCATION_API_KEY increases the allowance to roughly 50,000 queries per month and unlocks additional fields. The server is asynchronous (using httpx) and implemented as a FastMCP tool for straightforward integration.

Features

Comprehensive geolocation: country, region, city, latitude/longitude, ZIP/postal code, time zone.
Network details: ASN, ISP, domain, net speed, address/usage type.
Security & proxy detection: proxy type, provider, last seen, fraud scoring, threat flags.
Mobile metadata: MCC/MNC and mobile brand where available.
Currency & language info: currency code/name/symbol and primary language.
Asynchronous, non-blocking requests via httpx.
FastMCP-compatible tool (get_geolocation) for easy integration with Claude Desktop and other MCP clients.
Works without an API key (limited quota); supports API key via environment variable for higher quota and richer results.

Installation / Configuration

Prerequisites:

Python 3.8+
modelcontextprotocol environment (uv) — follow the MCP quickstart to install uv and set up your environment.

Clone and run locally:

git clone https://github.com/ip2location/mcp-ip2location-io.git
cd mcp-ip2location-io
# Run via uv (Model Context Protocol package manager)
uv --directory "$(pwd)/src" run server.py

Environment variable (optional but recommended):

export IP2LOCATION_API_KEY="your_api_key_here"
# On Windows PowerShell:
# $env:IP2LOCATION_API_KEY = "your_api_key_here"

Claude Desktop configuration example Add the MCP server entry into your claude_desktop_config.json so Claude Desktop can launch the server:

{
  "mcpServers": {
    "ip2locationio": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-ip2location-io/src",
        "run",
        "server.py"
      ],
      "env": {
        "IP2LOCATION_API_KEY": "<YOUR_API_KEY_IF_ANY>"
      }
    }
  }
}

Replace /path/to/mcp-ip2location-io with the actual path on your machine. Restart Claude Desktop (or your MCP client) after editing the config.

Troubleshooting:

Ensure uv is installed and on PATH.
Confirm Python and dependency versions (httpx, modelcontextprotocol) match requirements.
If responses are missing fields, check whether your API key tier supports those fields or hit rate limits.

Available Tools

get_geolocation

Description: Fetches geolocation and related metadata for a given IPv4 or IPv6 address.
Arguments:
- ip (string) — IPv4 or IPv6 address to query.
Returns: JSON string with geolocation and ancillary data. On failure, returns an error message string.

Sample usage (MCP client sends a tool call): { “tool”: “get_geolocation”, “args”: { “ip”: “8.8.8.8” } }

Sample (truncated) JSON response:

{
  "ip": "8.8.8.8",
  "country_name": "United States",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "zip_code": "94043",
  "time_zone": "America/Los_Angeles",
  "asn": 15169,
  "isp": "Google LLC",
  "domain": "google.com",
  "proxy": {
    "is_proxy": false,
    "proxy_type": null,
    "provider": null
  }
}

Common fields reference (partial)

Field	Description
country_name, country_code	Country information
region, city, zip_code	Administrative and postal data
latitude, longitude	Coordinates
time_zone	IANA time zone
asn, isp, domain	Network/Service provider data
proxy.*	Proxy/protection and threat indicators
currency_code, currency_name	Local currency
mcc, mnc	Mobile network codes (if applicable)

Use Cases

Enrich chat responses: A model can call the MCP tool to provide precise location context for an IP mentioned in conversation (e.g., “Where is 8.8.8.8 located?”).
Security triage: Integrate into incident-response assistants to check whether an IP is a known proxy or flagged for fraud.
Personalization: Geo-targeted content or time zone calculations in an assistant that adapts responses to user location derived from IP.
Data enrichment pipelines: Batch or on-demand augmentation of logs with ASN/ISP, timezone, and country fields.

Concrete examples

Developer debugging: “get_geolocation(ip=‘203.0.113.45’)” returns city/country and ASN to help trace traffic origin.
Threat analysis: Ask the model to check if an IP is a known proxy/provider and include last_seen and fraud_score fields.
Localization: Use time_zone and currency fields to format timestamps and prices appropriately.

License & Resources

Source: https://github.com/ip2location/mcp-ip2location-io
License details are included in the repository LICENSE file.
IP2Location.io signup and API docs: https://www.ip2location.io

This server is intended as a developer-facing tool to enable MCP-capable assistants to fetch IP-based contextual data reliably and with minimal setup.

IP2Location.io Geolocation MCP Server