ipgeolocation-io-mcp

# IPGeolocation.io MCP Server

[![SafeSkill](https://safeskill.dev/api/badge/ipgeolocation-io-mcp)](https://safeskill.dev/scan/ipgeolocation-io-mcp)

[![npm version](https://img.shields.io/npm/v/ipgeolocation-io-mcp?logo=npm&label=npm&color=CB3837)](https://www.npmjs.com/package/ipgeolocation-io-mcp)
[![GitHub release](https://img.shields.io/github/v/release/IPGeolocation/ipgeolocation-io-mcp?logo=github&label=release&color=181717)](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-live-0A7CFF?logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/?q=ipgeolocation)
[![Glama](https://img.shields.io/badge/Glama-listed-0A7CFF)](https://glama.ai/mcp/servers/IPGeolocation/ipgeolocation-io-mcp)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/IPGeolocation/ipgeolocation-io-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/IPGeolocation/ipgeolocation-io-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D22-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-MIT-16A34A)](https://github.com/IPGeolocation/ipgeolocation-io-mcp/blob/main/LICENSE)

Official MCP server for [IPGeolocation.io](https://ipgeolocation.io). Includes 16 MCP tools: IP geolocation, threat/VPN/proxy detection, timezone lookups and conversions, sunrise/sunset/moon data, ASN details, abuse contacts, and user-agent parsing. Seven tools work on the free plan (1,000 credits/day). Paid plans unlock all 16 plus bulk endpoints (up to 50,000 items per call; default 1,000, configurable via `IPGEOLOCATION_MCP_MAX_BULK_ITEMS`).

Works with Claude Desktop, Cursor, Windsurf, VS Code, Codex, Cline, Glama, and any other MCP client.

| Item | Value |
|------|-------|
| Package | `ipgeolocation-io-mcp` |
| Version | `2.0.0` |
| Transport | `stdio` |
| Node.js | `>=22` |

## Quick Start

1. [Create a free IPGeolocation API key](https://app.ipgeolocation.io/signup)

2. Cursor users can install in one click:

   [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=ipgeolocation&config=eyJjb21tYW5kIjoibnB4IC15IGlwZ2VvbG9jYXRpb24taW8tbWNwIiwiZW52Ijp7IklQR0VPTE9DQVRJT05fQVBJX0tFWSI6IiJ9fQ%3D%3D)

3. Add this to your MCP client config (see [Install by Client](#install-by-client) below for the exact config file path for your client):

```json
{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

4. Restart your client.

5. Test it: ask **"Where is 8.8.8.8 located?"**

## Table of Contents

- [Quick Start](#quick-start)
- [Install by Client](#install-by-client)
- [Verify It Works](#verify-it-works)
- [Tools by Plan](#tools-by-plan)
- [Tool Reference](#tool-reference)
- [Prompt Examples](#prompt-examples)
- [Example Answers and Tool Output](#example-answers-and-tool-output)
- [Error Codes](#error-codes)
- [How It Works](#how-it-works)
- [Caching](#caching)
- [Environment Variables](#environment-variables)
- [Building from Source](#building-from-source)
- [Docker](#docker)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [Pricing](#pricing)
- [Links](#links)
- [License](#license)
- [Privacy Policy](#privacy-policy)

## Install by Client

### Requirements

- Node.js 22 or later
- `npx` available in your terminal
- An IPGeolocation.io API key for most tools

`get_my_ip` works without an API key. Everything else requires one.

[Sign up for a free IPGeolocation API key](https://app.ipgeolocation.io/signup)

### Codex CLI

```bash
codex mcp add ipgeolocation --env IPGEOLOCATION_API_KEY=<YOUR_API_KEY> -- npx -y ipgeolocation-io-mcp
codex mcp list
```

Start a new Codex session after adding the server.

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

Restart Claude Desktop after saving. We also ship `manifest.json` for clients that support MCP Bundles.

### Cline

Open MCP Servers panel > **Configure** > **Advanced MCP Settings**. Add to `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

Restart Cline after saving.

### Cursor

One-click install:

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=ipgeolocation&config=eyJjb21tYW5kIjoibnB4IC15IGlwZ2VvbG9jYXRpb24taW8tbWNwIiwiZW52Ijp7IklQR0VPTE9DQVRJT05fQVBJX0tFWSI6IiJ9fQ%3D%3D)

Or add to `.cursor/mcp.json` manually:

```json
{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

Restart Cursor after saving.

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "ipgeolocation": {
      "command": "npx",
      "args": ["-y", "ipgeolocation-io-mcp"],
      "env": {
        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

Restart Windsurf after saving.

### VS Code / GitHub Copilot

Add to your VS Code `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "ipgeolocation": {
        "command": "npx",
        "args": ["-y", "ipgeolocation-io-mcp"],
        "env": {
          "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
        }
      }
    }
  }
}
```

Restart VS Code after saving.

### Glama

You can try the server on [Glama](https://glama.ai/mcp/servers/IPGeolocation/ipgeolocation-io-mcp) directly. Only `IPGEOLOCATION_API_KEY` is required. Leave other environment variable fields empty unless you want to change cache, timeout, or output limits.

If you don't have a key yet, [create a free IPGeolocation API key](https://app.ipgeolocation.io/signup).

### Any Other MCP Client

Use this config:

```json
{
  "command": "npx",
  "args": ["-y", "ipgeolocation-io-mcp"],
  "env": {
    "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
  }
}
```

## Verify It Works

Try these after setup:

| Prompt | Expected tool |
|--------|---------------|
| Where is 8.8.8.8 located? | `lookup_ip` |
| For IP 49.12.212.42, give me security verdict, company, ASN, and city. | `lookup_ip` with `fields` and `include=security` |
| Is 2.56.12.11 safe to allow and what is the abuse contact email? | `lookup_ip` with `include=security,abuse` |
| For AS1, list upstream ASN numbers only. | `lookup_asn` with `include=upstreams` |
| Convert 2026-03-07 09:30 from New York to Tokyo time. | `convert_timezone` |
| Give sunrise times for Karachi from 2026-03-10 to 2026-03-15. | `get_astronomy_time_series` |
| Parse this user agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 | `parse_user_agent` |

## Tools by Plan

### Free Plan

1,000 credits per day. These 7 tools are available:

| Tool | Credits | What it does |
|------|---------|--------------|
| `lookup_ip` | 1 | Location, timezone, currency, ASN for one IP |
| `get_my_ip` | 0 | Public IP of the machine running the server |
| `lookup_currency` | 1 | Currency and country metadata for one IP |
| `get_timezone` | 1 | Timezone by name, location, IP, airport code, or UN/LOCODE |
| `convert_timezone` | 1 | Convert time between two locations |
| `get_astronomy` | 1 | Sunrise, sunset, moonrise, moonset, twilight, moon phase for one date |
| `get_astronomy_time_series` | 1 | Daily astronomy data for a date range (up to 90 days) |

### Paid Plans

All 16 tools. Paid plans also add `network`, `company`, and extended `asn` fields to `lookup_ip`, plus the `include` parameter for `security`, `abuse`, `hostname`, `liveHostname`, `hostnameFallbackLive`, `user_agent`, `geo_accuracy`, `dma_code`, or `*`.

| Tool | Credits | What it does |
|------|---------|--------------|
| `bulk_lookup_ip` | 1 per IP | Batch geolocation, up to 50,000 IPs (default 1,000) |
| `check_security` | 2 | VPN, proxy, Tor, bot, spam, and threat flags |
| `bulk_security_check` | 2 per IP | Batch threat checks |
| `lookup_company` | 1 | Company name and ASN holder for one IP |
| `lookup_network` | 1 | Route prefix, connection type, anycast status |
| `parse_user_agent` | 1 | Parse one UA string into browser, device, OS, engine |
| `bulk_parse_user_agent` | 1 per UA | Batch UA parsing, up to 50,000 strings (default 1,000) |
| `lookup_asn` | 1 | ASN details, peers, upstreams, downstreams, routes, WHOIS |
| `get_abuse_contact` | 1 | Abuse contact emails, phone, address, route |

**Credit math for `lookup_ip` with `include`:**

| Combination | Total credits |
|-------------|---------------|
| Base lookup | 1 |
| `include=security` | 3 |
| `include=abuse` | 2 |
| `include=*` | 4 |
| `include=security&fields=security` | 2 |
| `include=abuse&fields=abuse` | 1 |

For current plan details and pricing, see the [IPGeolocation pricing page](https://ipgeolocation.io/pricing.html).

## Tool Reference

### lookup_ip

Single IP or domain lookup. **Free and paid. 1 credit.**

Use this when you need location, timezone, currency, or ASN for one IP address. On paid plans you can add `include` modules to pull security, abuse, or hostname data in the same call, which avoids extra requests.

Free plan returns base location, country metadata, currency, timezone, and basic ASN. Paid plans add `network`, `company`, extended ASN, and the `include` parameter. Note that domain lookups require a paid plan.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `ip` | No | IPv4, IPv6, or domain. Domain lookup requires a paid plan. |
| `lang` | No | Resp