ipatlas
Hosted remote MCP server · nothing to install

Give your AI agent location awareness

Point Claude Desktop, Claude Code, Cursor or any Model Context Protocol (MCP) client at https://api.ipatlas.dev/mcp. Your agent can check its own public IP, look up any IPv4 or IPv6 address, or batch up to 100 IPs in one call.

Copy setup config →OpenAPI 3.1llms.txt
// Remote MCP Streamable HTTP endpoint
{
  "mcpServers": {
    "ipatlas": {
      "url": "https://api.ipatlas.dev/mcp",
      "headers": {
        "Authorization": "Bearer ipa_your_key_here"
      }
    }
  }
}

// Tools exposed to your agent:
// - lookup_ip({ "ip": "8.8.8.8" })
// - my_location({})
// - lookup_batch({ "ips": ["8.8.8.8", "1.1.1.1"] })

Built-in tools

Three tools ready as soon as you connect.

Our hosted MCP server speaks standard MCP Streamable HTTP (JSON-RPC 2.0 over POST https://api.ipatlas.dev/mcp). There is no package to install and no local database to keep updated.

lookup_ip

Pass any public IPv4 or IPv6 address ({"ip": "8.8.8.8"}) to get country, two-letter country code, EU membership, region, approximate city, coordinates, IANA time zone and network provider (asn).

my_location

Takes no arguments ({}) and returns the public IP address and location of the machine calling the API — handy when an agent needs your current country, local currency or time zone.

lookup_batch

Look up 1 to 100 public IPv4 or IPv6 addresses in a single tool call ({"ips": ["8.8.8.8", "2606:4700:4700::1111"]}) when investigating access logs or sign-ins. Each IP in the batch counts as one lookup against your quota.

Copy & paste setup

Connect your client in under a minute.

You can try the endpoint immediately without an API key (up to 1,000 lookups a day per IP), or add a free API key for 50,000 lookups a month.

1. Claude Code (CLI)

Add the hosted HTTP MCP server with one command. Omit --header to use the keyless tier, or pass your API key for 50,000+ lookups a month:

# Keyless (up to 1,000 lookups/day per IP)
claude mcp add --transport http ipatlas https://api.ipatlas.dev/mcp

# With your API key (50,000 free lookups/month)
claude mcp add --transport http ipatlas https://api.ipatlas.dev/mcp \
  --header "Authorization: Bearer ipa_your_key_here"

2. Claude Desktop (claude_desktop_config.json)

Claude Desktop's config file starts local programs, so use the small mcp-remote bridge (needs Node.js). Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop. Replace ipa_your_key_here with your free key. For a quick try without a key, use the keyless version below (1,000 lookups a day per IP).

{
  "mcpServers": {
    "ipatlas": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.ipatlas.dev/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ipa_your_key_here"
      }
    }
  }
}

Keyless version:

{
  "mcpServers": {
    "ipatlas": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.ipatlas.dev/mcp"]
    }
  }
}

3. Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)

Add the remote Streamable HTTP server to your project or global Cursor MCP config (omit headers to use the keyless tier):

{
  "mcpServers": {
    "ipatlas": {
      "url": "https://api.ipatlas.dev/mcp",
      "headers": {
        "Authorization": "Bearer ipa_your_key_here"
      }
    }
  }
}

4. Generic MCP client (Streamable HTTP / JSON-RPC 2.0)

Any custom agent or MCP client can call POST https://api.ipatlas.dev/mcp directly with Content-Type: application/json and an optional Authorization: Bearer ipa_... (or X-API-Key: ipa_...) header:

# 1. Initialize session
curl -sS https://api.ipatlas.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IPATLAS_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

# 2. List available tools
curl -sS https://api.ipatlas.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Call lookup_ip (or my_location / lookup_batch)
curl -sS https://api.ipatlas.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IPATLAS_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_ip","arguments":{"ip":"8.8.8.8"}}}'

Prefer OpenAPI tool calling or plain REST? Point your framework at https://ipatlas.dev/openapi.json or https://ipatlas.dev/llms.txt.

Accuracy, privacy & limits

Honest data and predictable quotas.

AI agents work best when tool responses are fast, structured and upfront about what IP geolocation can and cannot tell you.

Honest accuracy note

Country is usually right. City is approximate and can be off by tens of kilometres, especially on mobile networks, VPNs and corporate connections. Time zone is derived from coordinates. Never use IP geolocation alone when you need certainty.

Looked-up IPs are never logged

Lookups run in memory against the monthly DB-IP Lite dataset (CC BY 4.0). We never write the IP addresses your agent looks up to disk or store them in our database.

Same plans, hard caps

MCP calls share the exact same quotas and rate limits as our REST API: 1,000/day keyless, 50,000/month free, or paid plans at $9 (500k), $29 (3M) and $99 (15M) a month with hard 429 caps and no surprise bills.

Frequently asked questions

Do I need an API key to test the MCP server?

No. You can connect to https://api.ipatlas.dev/mcp without an Authorization header and run up to 1,000 lookups a day per IP address (10 requests/second). When you want 50,000 lookups a month, create a free API key with your email — no credit card required.

How does lookup_batch count toward my quota?

lookup_batch accepts 1 to 100 public IPv4 or IPv6 addresses per call. All IPs are validated (format and public address check) before charging quota; if any entry is invalid or private/reserved, the call returns an MCP tool error (isError: true) and charges nothing. Each IP in a valid batch counts as one lookup against your rate limit and daily/monthly quota.

What happens if my agent passes a private IP or hits a rate limit?

Private, loopback or invalid IP addresses (such as 192.168.1.1) return an MCP tool error (isError: true) explaining why the address has no public geolocation data. When a rate limit or quota is reached, the server returns HTTP 429 with Retry-After plus a structured tool error with the window and reset delay.

Where can I find the OpenAPI spec and llms.txt?

The OpenAPI 3.1 specification is at https://ipatlas.dev/openapi.json and our compact LLM summary is at https://ipatlas.dev/llms.txt. Full REST examples in curl, JavaScript, Python, Go, PHP and Ruby are in the API documentation.