# mcp-ip2location

**Give your AI assistant a sense of place.**

An [MCP](https://modelcontextprotocol.io) (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](https://www.ip2location.io) and
[IP2WHOIS](https://www.ip2whois.com).

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

```bash
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:

```json
{
  "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`):

```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`:

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

**Claude Code** (CLI):

```bash
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