mcp-ip2location

mcp-ip2location

Give your AI assistant a sense of place.

An MCP (Model Context Protocol) serverthat lets Claude Desktop, Claude Code, or any MCP-compatible client performIP geolocation, proxy detection, and domain WHOIS lookups natively — poweredby IP2Location.io andIP2WHOIS.

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

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 theapp: open Settings → Developer → Edit Config. This opens the correctclaude_desktop_config.json (creating it if needed), wherever your installkeeps it — you don't have to hunt for the path.

If you'd rather open it manually, the location depends on how Claude Desktopwas 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 packagedapp data instead, e.g.C:\Users\<you>\AppData\Local\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.jsonThe Claude_<id> folder name varies per machine — using Edit Configavoids having to find it.

Add the mcpServers block to that file. If the file already has other keysor 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 absolutepath to dist\index.js in the folder where you cloned this project(e.g. C:\\src\\IP2\\mcp-ip2location\\dist\\index.js). Keep the doubledbackslashes.
2. YOUR_KEY → your real IP2Location.io API key from your accountdashboard.

The server won't start until both are correct.

Notes for Windows:

• Use the full absolute path to dist\index.js and double thebackslashes (\\) — JSON treats a single \ as an escape character.
• Run npm install and npm run build first, so dist\index.js actuallyexists before you point at it.
• A stray comma or missing brace will silently stop all servers fromloading, 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 appearautomatically. 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 serverisn't tied to Claude — the same dist/index.js works with any MCP-compatiblehost. Common ones include Claude Desktop & Claude Code, OpenAI ChatGPT,Google Gemini, GitHub Copilot / VS Code, Cursor, Windsurf, Zed, and localrunners like Ollama and LM Studio.

The server definition is the same everywhere (command, args, env) — onlywhere 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 thatapp'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 currentdata 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 includesthem 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 toolerrors so it can explain them to you rather than failing silently.

License

MIT