mcp-ip2location

Give your AI assistant a sense of place.

An MCP (Model Context Protocol) server that lets Claude Desktop, Claude Code, or any MCP-compatible client perform IP geolocation, proxy detection, and domain WHOIS lookups natively — powered by IP2Location.io and IP2WHOIS.

Once connected, you can simply ask your assistant things like:

"Where are these 5 IPs from my nginx log located, and are any of them proxies?" "How old is the domain in this suspicious invoice email?" "Which of these login IPs are outside Malaysia?"

…and it answers with real data instead of guessing.

Tools provided

Tool	What it does
ip_geolocation	Country, region, city, coordinates, timezone, ASN for one IP (plus ISP, usage type, mobile carrier and more on paid plans)
proxy_check	Is this IP a known proxy/VPN/anonymizer?
whois_lookup	Domain age, registrar, expiry, nameservers, registrant
bulk_geolocate	Up to 50 IPs in one request — ideal for pasted log excerpts
hosted_domains	Reverse-IP lookup: list domains hosted on a given IP

Setup

git clone https://github.com/eweley95/mcp-ip2location
cd mcp-ip2location
npm install
npm run build

Get a free API key at https://www.ip2location.io (50,000 IP queries + 500 WHOIS queries per month — the same key covers both).

Add to Claude Desktop

The easiest and most reliable way to find the config file is from inside the app: open Settings → Developer → Edit Config. This opens the correct claude_desktop_config.json (creating it if needed), wherever your install keeps it — you don't have to hunt for the path.

If you'd rather open it manually, the location depends on how Claude Desktop was installed:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows (installer / .exe version): %APPDATA%\Claude\claude_desktop_config.json (i.e. C:\Users\<you>\AppData\Roaming\Claude\)
• Windows (Microsoft Store version): the file lives under the packaged app data instead, e.g. C:\Users\<you>\AppData\Local\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json The Claude_<id> folder name varies per machine — using Edit Config avoids having to find it.

Add the mcpServers block to that file. If the file already has other keys or other servers, merge this entry in rather than overwriting it:

{
  "mcpServers": {
    "ip2location": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-ip2location\\dist\\index.js"],
      "env": { "IP2LOCATION_API_KEY": "YOUR_KEY" }
    }
  }
}

Before saving, replace the two placeholders with your own values:

1. C:\\path\\to\\mcp-ip2location\\dist\\index.js → the full absolute path to dist\index.js in the folder where you cloned this project (e.g. C:\\src\\IP2\\mcp-ip2location\\dist\\index.js). Keep the doubled backslashes.
2. YOUR_KEY → your real IP2Location.io API key from your account dashboard.

The server won't start until both are correct.

Notes for Windows:

• Use the full absolute path to dist\index.js and double the backslashes (\\) — JSON treats a single \ as an escape character.
• Run npm install and npm run build first, so dist\index.js actually exists before you point at it.
• A stray comma or missing brace will silently stop all servers from loading, so validate the JSON if the tools don't appear.

Then fully quit Claude Desktop (right-click the system-tray icon → Quit, not just closing the window) and reopen it. The five tools appear automatically. Try it with: "Where is the IP 8.8.8.8 located?"

Works with other MCP clients

MCP is an open standard (governed by the Linux Foundation), so this server isn't tied to Claude — the same dist/index.js works with any MCP-compatible host. Common ones include Claude Desktop & Claude Code, OpenAI ChatGPT, Google Gemini, GitHub Copilot / VS Code, Cursor, Windsurf, Zed, and local runners like Ollama and LM Studio.

The server definition is the same everywhere (command, args, env) — only where you register it differs per app. A few examples:

Cursor — create .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "ip2location": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-ip2location\\dist\\index.js"],
      "env": { "IP2LOCATION_API_KEY": "YOUR_KEY" }
    }
  }
}

VS Code (Copilot / Agent mode) — add to .vscode/mcp.json:

{
  "servers": {
    "ip2location": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-ip2location\\dist\\index.js"],
      "env": { "IP2LOCATION_API_KEY": "YOUR_KEY" }
    }
  }
}

Claude Code (CLI):

claude mcp add ip2location \
  --env IP2LOCATION_API_KEY=YOUR_KEY \
  -- node /absolute/path/to/mcp-ip2location/dist/index.js

For other hosts (ChatGPT, Gemini, Ollama, LM Studio, etc.), consult that app's "MCP servers" or "connectors" settings and supply the same three values. Remember to replace the path and YOUR_KEY in every case.

Examples

Once connected, just ask in plain language — Claude picks the right tool. Here is one example per tool:

ip_geolocation — where is a single IP?

You:    Where is the IP 8.8.8.8 located?
Claude: [calls ip_geolocation]
        8.8.8.8 is in Mountain View, California, United States (AS15169,
        Google LLC). Not flagged as a proxy.

proxy_check — can I trust this IP?

You:    Is 185.220.101.45 a proxy or VPN?
Claude: [calls proxy_check]
        Yes — 185.220.101.45 is flagged as a proxy/VPN/anonymizer. It's in
        Germany on AS60729, a range well known for Tor exit nodes.

whois_lookup — how old / trustworthy is a domain?

You:    How old is the domain example.com?
Claude: [calls whois_lookup]
        example.com was first registered on 1995-08-14 (about 30 years ago),
        last updated 2024-08-14, and expires 2025-08-13. Registrar: RESERVED
        — Internet Assigned Numbers Authority. A long-established domain.

bulk_geolocate — analyse a list of IPs at once

You:    Where are these from, and any proxies?
        185.220.101.45, 8.8.8.8, 175.139.142.25
Claude: [calls bulk_geolocate]
        185.220.101.45 — Germany, AS60729 — flagged as proxy (Tor range)
        8.8.8.8        — United States, Google LLC — not flagged
        175.139.142.25 — Malaysia, TM Net — not flagged

hosted_domains — what else is on this server? (reverse IP)

You:    What domains are hosted on the IP 104.26.10.78?
Claude: [calls hosted_domains]
        That IP hosts 1,240 domains across 25 pages (it's a shared
        Cloudflare address). The first page includes example1.com,
        example2.net, ... — want me to pull a specific page?

The exact values above are illustrative; live results depend on current data and your plan's detail level.

Notes

• The server speaks MCP over stdio; no port is opened.
• Plan-dependent fields. The free plan returns country, region, city, coordinates, timezone, ASN and the is_proxy flag. Richer fields (ISP, domain, usage type, mobile carrier, elevation, detailed proxy typing, etc.) are returned only on paid IP2Location.io plans — ip_geolocation includes them automatically when your plan provides them, and omits them otherwise.
• bulk_geolocate uses the dedicated bulk endpoint (one request for all IPs) and falls back to per-IP lookups if that endpoint isn't on your plan.
• Errors (invalid IP, quota exceeded) are returned to the assistant as tool errors so it can explain them to you rather than failing silently.

License

MIT