IPGeolocation.io MCP Server

IPGeolocation.io MCP Server

The official IPGeolocation.io MCP server provides 17 tools for accurate IP geolocation, company information, ASN and network data, IP security (VPN, proxy, Tor, bot, hosting and spam detection), abuse contacts, time zones, astronomy, currency 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 for configuration examples.

Published version: [2.0.3](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases/tag/v2.0.3).

The install commands follow npm's latest tag, including future major releases. Restart the server to load an update. Source and Docker installations need a rebuild.

Quick Start

1. Create a free IPGeolocation.io API key.
2. Merge this entry into your client's private configuration, keeping any existing servers. See Install by Client for the configuration location. Cursor also has a one-click installer.

{

"mcpServers": { "ipgeolocation": { "command": "npx", "args": ["-y", "ipgeolocation-io-mcp@latest"], "env": { "IPGEOLOCATION_API_KEY": " " } } } }

1. Reload the server or restart your client.
2. Ask "Where is 8.8.8.8 located?"

Table of Contents

• Quick Start
• Install by Client
• Verify It Works
• Tools by Plan
• Tool Reference
• Prompt Examples
• Example Answers and Tool Output
• Error Codes
• How It Works
• Caching
• Cached Result Pagination
• Environment Variables
• Building from Source
• Docker
• Testing
• Troubleshooting
• Pricing
• Links
• License
• 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.io API key

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 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.

codex mcp add ipgeolocation --env "IPGEOLOCATION_API_KEY=$IPGEOLOCATION_API_KEY" -- npx -y ipgeolocation-io-mcp@latest

codex mcp list

Start a new Codex session after adding the server.

Claude Desktop

Install the published server from its Claude Marketplace listing. 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. 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 into mcpServers.

Fully quit and reopen Claude Desktop after saving. See the official local-server setup guide.

For clients that install MCP Bundles, download the published v2.0.3 .mcpb bundle from GitHub 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 under mcpServers in the settings JSON. Cline CLI uses ~/.cline/data/settings/cline_mcp_settings.json by default. See Cline's MCP guide.

Restart Cline after saving.

Cursor

One-click install:

Or add to .cursor/mcp.json for this project, or ~/.cursor/mcp.json for all projects. See Cursor's MCP guide.

{

"mcpServers": { "ipgeolocation": { "type": "stdio", "command": "npx", "args": ["-y", "ipgeolocation-io-mcp@latest"], "env": { "IPGEOLOCATION_API_KEY": " " } } } }

Restart Cursor after saving.

Cursor plugin

This repository includes a Cursor plugin for ipgeolocation-io-mcp. The plugin runs locally over stdio and requires Node.js 22 or later.

To install it locally, clone this repository into a new directory under ~/.cursor/plugins/local/, reload Cursor, and open Customize > Plugins.

• Local plugin: set IPGEOLOCATION_API_KEY in the environment that launches Cursor. The plugin reads the key from that environment.
• Marketplace install: set the key in the plugin's private configuration.

With an empty or unset API key, get_my_ip still works. API tools that require a key return a missing-key error without sending a request.

To load a local checkout in Cursor CLI:

agent --plugin-dir /absolute/path/to/ipgeolocation-io-mcp

API requests that need a key use your account's plan and credits. The get_cached_result tool reads saved response pages without making another API request.

Install this server by only one method, because using more than one creates duplicate tool entries. You can keep any other servers in your existing configuration.

Windsurf / Cascade

In Cascade's ... (Actions) menu, choose Open MCP config file in the MCPs section. Merge the Quick Start entry into the file opened by your installed version; configuration paths vary by release. See the vendor's Cascade MCP guide for the active agent and configuration location in newer releases.

Save the file and reload the server in the client.

Kiro Powers

The Kiro Power provides 17 tools for IP geolocation, company information, ASN and network data, IP security (VPN, proxy, Tor, bot, hosting and spam detection), abuse contacts, time zones, astronomy, currency data and user-agent parsing. It runs ipgeolocation-io-mcp locally over stdio, follows npm's latest tag and requires Node.js 22 or later. Import the packaging/kiro folder through Powers > Add Custom Power and follow the setup guide to configure your private API key. Most tools require a key; access and credits depend on your plan.

VS Code / GitHub Copilot

Run MCP: Add Server from the Command Palette, choose a local command, and use npx -y ipgeolocation-io-mcp@latest. 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.

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.

Glama

You can try the server on Glama 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.io API key.

Any Other MCP Client

Use the ipgeolocation server entry from 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:

Tools by Plan

Version 2.0.3 exposes 16 API tools and get_cached_result, a zero-credit page reader. Bulk tools accept 250 inputs by default; the effective ceiling is the lower of the two item-limit settings.

Listed costs apply to successful upstre