ipgeolocation-io-mcp

IPGeolocation.io MCP Server

Official MCP server for 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 1,000 items per call).

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

Item	Value
Package	ipgeolocation-io-mcp
Version	1.0.17
Transport	stdio
Node.js	>=18

Quick Start

1. Create a free IPGeolocation API key

2. Cursor users can install in one click:

   

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

{
  "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
• Install by Client
• Verify It Works
• Tools by Plan
• Tool Reference
• Prompt Examples
• Example Answers and Tool Output
• Error Codes
• How It Works
• Caching
• Environment Variables
• Building from Source
• Docker
• Testing
• Troubleshooting
• Pricing
• Links
• License
• Privacy Policy

Install by Client

Requirements

• Node.js 18 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

Codex CLI

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:

{
  "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:

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

Restart Cline after saving.

Cursor

One-click install:

Or add to .cursor/mcp.json manually:

{
  "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:

{
  "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:

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

Any Other MCP Client

Use this config:

{
  "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 for up to 1,000 IPs
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 for up to 1,000 strings
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.

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	Response language. Non-English requires a paid plan.
include	No	Extra modules: security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or *

---

README truncated. View full README on GitHub.