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)

Use the official [IPGeolocation.io](https://ipgeolocation.io) MCP server for IP geolocation, security indicators, ASN data, and abuse contacts. It also provides time zone conversions, sun and moon data, and user-agent parsing.

MCP (Model Context Protocol) connects your client to these tools. Your client or host must support launching a local command over `stdio`. See [Install by Client](#install-by-client) for configuration examples.

**This README describes [2.0.1](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases/tag/v2.0.1).** The `npx` commands and Cursor install link below install the latest published npm package. See the [changelog](CHANGELOG.md) for changes to pagination, limits, and error handling.

| Item | Value |
|------|-------|
| Package | `ipgeolocation-io-mcp` |
| Version | `2.0.1` |
| Release date | 2026-10-11 |
| Transport | `stdio` |
| Node.js | `>=22` |

## Quick Start

1. [Create a free IPGeolocation API key](https://app.ipgeolocation.io/signup).
2. Merge this entry into your client's private configuration, keeping any existing servers. See [Install by Client](#install-by-client) for the configuration location. Cursor also has a [one-click installer](#cursor).

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

3. Reload the server or restart your client.
4. 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)
- [Cached Result Pagination](#cached-result-pagination)
- [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 for npm/source installs, or a bundle host with a compatible Node.js runtime
- `npx` available for the npm configuration examples
- An IPGeolocation.io API key for most API tools

Use a supported Node.js release with its latest security updates.

`get_my_ip` requires no API key. The other 15 API tools require one. `get_cached_result` reads results already held in memory; use the same API key as the original lookup.

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

Use a private user configuration or your client's secret/environment settings for the real key. Keep keys out of committed project configuration. Each client below uses the [Quick Start server entry](#quick-start) unless its format differs.

### Codex CLI

Set `IPGEOLOCATION_API_KEY` in your private shell environment before running these commands. The variable reference keeps the key value out of the command you type and its shell history.

```bash
codex mcp add ipgeolocation --env "IPGEOLOCATION_API_KEY=$IPGEOLOCATION_API_KEY" -- npx -y ipgeolocation-io-mcp
codex mcp list
```

Start a new Codex session after adding the server.

### Claude Desktop

Install the published server from its [Claude Marketplace listing](https://claude.com/marketplace/connectors/ipgeolocation-io-mcp-server). In Claude Desktop, open **Settings > Extensions > Browse extensions**, find **IPGeolocation.io MCP Server**, and configure your API key during installation. See [Anthropic's desktop extension guide](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop). The directory distributes the approved published bundle; its refresh can lag GitHub Releases. Check the installed version, or download the versioned bundle below.

For manual npm configuration, open **Settings > Developer > Edit Config** in Claude Desktop. This opens `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Merge the [Quick Start entry](#quick-start) into `mcpServers`.

Fully quit and reopen Claude Desktop after saving. See the [official local-server setup guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers).

For clients that install MCP Bundles, download the published [v2.0.1 `.mcpb` bundle](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases/download/v2.0.1/ipgeolocation-ipgeolocation-io-mcp-2.0.1.mcpb) from [GitHub Releases](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases). The bundle contains the server and its dependencies; its host still needs a Node.js 22+ runtime. Enter your API key when the host prompts for bundle configuration.

### Cline

In Cline, open **MCP Servers > Configure > Configure MCP Servers**. Add the [Quick Start entry](#quick-start) under `mcpServers` in the settings JSON. Cline CLI uses `~/.cline/data/settings/cline_mcp_settings.json` by default. See [Cline's MCP guide](https://docs.cline.bot/mcp/mcp-overview).

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=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImlwZ2VvbG9jYXRpb24taW8tbWNwIl0sImVudiI6eyJJUEdFT0xPQ0FUSU9OX0FQSV9LRVkiOiIifX0%3D)

Or add to `.cursor/mcp.json` for this project, or `~/.cursor/mcp.json` for all projects. See [Cursor's MCP guide](https://cursor.com/docs/mcp).

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

Restart Cursor after saving.

### Windsurf / Cascade

In Cascade's **... (Actions)** menu, choose **Open MCP config file** in the MCPs section. Merge the [Quick Start entry](#quick-start) into the file opened by your installed version; configuration paths vary by release. See the [vendor's Cascade MCP guide](https://docs.devin.ai/desktop/cascade/mcp) for the active agent and configuration location in newer releases.

Save the file and reload the server in the client.

### VS Code / GitHub Copilot

Run **MCP: Add Server** from the Command Palette, choose a local command, and use `npx -y ipgeolocation-io-mcp`. Choose **Copilot Global** for private user settings or **.mcp.json** for a portable workspace configuration. Add `IPGEOLOCATION_API_KEY` to the server's environment.

The portable `.mcp.json` format uses the top-level `mcpServers` object shown in [Quick Start](#quick-start).

Use the server's **Start** action and approve its configuration when prompted. Existing `.vscode/mcp.json` files use a top-level `servers` object instead. See [VS Code's MCP setup guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

### 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 the `ipgeolocation` server entry from [Quick Start](#quick-start) in your client's configuration format. The client must support launching a local `stdio` process. A client that accepts only a remote MCP URL needs a hosted endpoint; this package supplies the server command.

## 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 threat indicators, company, ASN, and city. | `lookup_ip` with `fields` and `include=security` |
| Show threat indicators and the abuse contact email for 2.56.12.11. | `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

Version 2.0.1 exposes 16 API tools and `get_cached_result`,