MCP Server

IP-Sonar provides a Model Context Protocol (MCP) server that allows AI assistants like Claude to directly access IP geolocation data. This enables AI models to look up geographic information for IP addresses seamlessly within conversations.

What is MCP?

Model Context Protocol (MCP) is a standard that allows AI assistants to securely connect to external data sources and services. Through MCP, AI models can access real-time information and perform actions beyond their training data.

Our MCP Server address

https://api.ip-sonar.com/mcp

Getting Started

1. Get Your API Key

2. Connection examples

Claude Code

claude mcp add --transport http ip-sonar https://api.ip-sonar.com/mcp \
  --header "X-Api-Key: your-api-key-here"

OpenAI

Available Tools

lookup_ip

Retrieves geolocation information for a single IP address.

Parameters:

ip (required): IPv4 or IPv6 address to lookup
locale_code (optional): Language code for localized names (e.g., “en”, “es”, “fr”, “de”)

Response includes:

Country code and name
City name
Continent information
Geographic coordinates (latitude/longitude)
Administrative subdivisions
Postal code
Timezone
EU membership status
Accuracy radius

lookup_batch

Processes multiple IP addresses in a single request for improved efficiency.

Parameters:

ips (required): Array of IP addresses to lookup
locale_code (optional): Language code for localized names

Response:

Array of geolocation results
Total count of processed addresses
Individual error handling per IP address

Rate Limiting

Rate limiting follows the same rules as the REST API:

Free Plan: 31k requests per month
Paid Plan: Higher limits based on subscription
Batch Requests: Each IP address in a batch counts as one request

When rate limits are exceeded, the server returns descriptive error messages with current quota information.

Error Handling

The MCP server provides structured error responses:

{
  "error": "Monthly usage limit exceeded",
  "rate_limit": {
    "limit": 31000,
    "remaining": 0,
    "reset": 1735689600
  }
}

Common error scenarios:

Invalid API key
Monthly quota exceeded
Invalid IP address format
IP address not found in database

How to Use

Once connected, you can ask your AI assistant to look up IP addresses naturally:

“What’s the location of IP address 216.8.112.108?”
“Look up these IPs: 216.8.112.108, 215.8.112.109, and 214.8.112.108”
“Find the country and city for 216.8.112.108”

The AI assistant will use the MCP tools automatically to provide accurate geolocation information.