IPGeolocation.io MCP Server

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

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

3. Claude Desktop

Add to claude_desktop_config.json :

1{
2  "mcpServers": {
3    "ipgeolocation": {
4      "command": "npx",
5      "args": ["-y", "ipgeolocation-io-mcp"],
6      "env": {
7        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
8      }
9    }
10  }
11}

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

4. Cline

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

1{
2  "mcpServers": {
3    "ipgeolocation": {
4      "command": "npx",
5      "args": ["-y", "ipgeolocation-io-mcp"],
6      "env": {
7        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
8      }
9    }
10  }
11}

Restart Cline after saving.

5. Cursor

Add to .cursor/mcp.json :

1{
2  "mcpServers": {
3    "ipgeolocation": {
4      "command": "npx",
5      "args": ["-y", "ipgeolocation-io-mcp"],
6      "env": {
7        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
8      }
9    }
10  }
11}

Restart Cursor after saving.

6. Windsurf

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

1{
2  "mcpServers": {
3    "ipgeolocation": {
4      "command": "npx",
5      "args": ["-y", "ipgeolocation-io-mcp"],
6      "env": {
7        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
8      }
9    }
10  }
11}

Restart Windsurf after saving.

7. VS Code / GitHub Copilot

Add to your VS Code settings.json :

1{
2  "mcp": {
3    "servers": {
4      "ipgeolocation": {
5        "command": "npx",
6        "args": ["-y", "ipgeolocation-io-mcp"],
7        "env": {
8          "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
9        }
10      }
11    }
12  }
13}

Restart VS Code after saving.

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

9. Any Other MCP Client

Use this config:

1{
2  "command": "npx",
3  "args": ["-y", "ipgeolocation-io-mcp"],
4  "env": {
5    "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
6  }
7}

1. Free Plan

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

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

Credit math for lookup_ip with include :

For current plan details and pricing, see the IPGeolocation pricing page.

1. 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		IPv4, IPv6, or domain. Domain lookup requires a paid plan.
lang		Response language. Non-English requires a paid plan.
include		Extra modules: security , abuse , hostname , liveHostname , hostnameFallbackLive , user_agent , geo_accuracy , dma_code , or *
fields		Comma-separated fields to return
excludes		Comma-separated fields to exclude
force_refresh		Skip the cache and hit the API directly

Tip: combining include with fields can cut your credit cost. For example, include=security&fields=security costs 2 credits instead of 3 because you skip the base geolocation response. Similarly, include=abuse&fields=abuse costs 1 credit instead of 2.

2. bulk_lookup_ip

Batch IP lookup. Paid. 1 credit per IP.

Takes an array of IPs or domains (up to 1,000 by default, configurable with IPGEOLOCATION_MCP_MAX_BULK_ITEMS ). Supports the same include , fields , and excludes options as lookup_ip .

Parameter	Required	Description
ips		Array of IP addresses or domains
lang		Response language
include		Extra modules per IP
fields		Comma-separated fields to return per IP
excludes		Comma-separated fields to exclude per IP
force_refresh		Skip the cache

3. get_my_ip

Returns the public IP of the machine running the server. Free. 0 credits. No API key needed.

Takes no parameters. Always hits the network (not cached). Useful as a quick check to confirm the server process is up.

4. check_security

Threat and anonymity data for one IP. Paid. 2 credits.

Returns threat score, VPN/proxy/Tor flags, provider names, confidence scores, bot/spam indicators, anonymity flags, and cloud-provider status.

If the same prompt also asks for location, ASN, or abuse data, you're better off using lookup_ip with include=security because it bundles everything in one call (3 credits total instead of 2 + 1 separately).

Parameter	Required	Description
ip		IP address to check
fields		Comma-separated fields to return
excludes		Comma-separated fields to exclude
force_refresh		Skip the cache

5. bulk_security_check

Batch version of check_security . Paid. 2 credits per IP.

Parameter	Required	Description
ips		Array of IP addresses
fields		Comma-separated fields to return per IP
excludes		Comma-separated fields to exclude per IP
force_refresh		Skip the cache

6. get_timezone

Current time and timezone details for a location. Free and paid. 1 credit.

Accepts IANA timezone names, coordinates, IP addresses, airport codes (IATA/ICAO), or UN/LOCODEs. The response includes timezone offsets, date/datetime variants, current_time , current_time_unix , time_24 , time_12 , week , month , year , timezone abbreviations, and DST transition details.

Always hits the network (not cached) because it returns the current time.

Parameter	Required	Description
tz		IANA timezone name (e.g., America/New_York )
lat + long		Latitude and longitude
location		City or address string
ip		IP address
iata_code		IATA airport code
icao_code		ICAO airport code
lo_code		UN/LOCODE
lang		Response language. Non-English requires a paid plan.

7. convert_timezone

Converts a time between two locations. Free and paid. 1 credit.

Takes the same location input types as get_timezone for both source and destination. If you leave out the time parameter, it converts the current time. Always hits the network (not cached).

Parameter	Required	Description
time		yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss . Defaults to now.
tz_from / tz_to		IANA timezone names
lat_from + long_from		Source coordinates
lat_to + long_to		Destination coordinates
location_from / location_to		City/address strings
iata_from / iata_to		IATA airport codes
icao_from / icao_to		ICAO airport codes
locode_from / locode_to		UN/LOCODEs

8. get_astronomy

Sun and moon data for one location on one date. Free and paid. 1 credit.

Returns sunrise, sunset, moonrise, moonset, morning and evening twilight, solar noon, day length, moon phase, sun/moon status flags, and live sun/moon position (altitude, azimuth).

Always hits the network (not cached) because skipping date defaults to today.

Parameter	Required	Description
lat + long		Coordinates (highest priority when given)
location		City or address
ip		IP address
date		YYYY-MM-DD . Defaults to today.
elevation		Meters, 0 to 10000
time_zone		IANA name to control output times
lang		Response language. Non-English requires a paid plan.

9. get_astronomy_time_series

Astronomy data for a date range, up to 90 days. Free and paid. 1 credit per request.

Each daily entry includes mid_night , night_end , morning , sunrise , sunset , evening , night_begin , sun_status , solar_noon , day_length , moon_phase , moonrise , moonset , and moon_status . Use this instead of calling get_astronomy repeatedly for a range.

Parameter	Required	Description
dateStart		Start date ( YYYY-MM-DD )
dateEnd		End date ( YYYY-MM-DD ). Max span: 90 days.
lat + long		Coordinates (highest priority when given)
location		City or address
ip		IP address
elevation		Meters
time_zone		IANA name to control output times
lang		Response language. Non-English requires a paid plan.
force_refresh		Skip the cache

10. parse_user_agent

Parses one UA string into browser, device, OS, and engine data. Paid. 1 credit.

Also classifies bots and crawlers. Note: this parses the uaString you pass in. It does not infer a caller UA from the MCP connection itself.

Parameter	Required	Description
uaString		The user-agent string to parse
force_refresh		Skip the cache

Returns name , type , version , device , engine , and operating_system .

11. bulk_parse_user_agent

Batch version of parse_user_agent . Paid. 1 credit per string.

Takes up to 1,000 strings per request by default (configurable with IPGEOLOCATION_MCP_MAX_BULK_ITEMS ).

Parameter	Required	Description
uaStrings		Array of user-agent strings
force_refresh		Skip the cache

12. lookup_company

Returns just the company name and ASN holder for one IP. Paid. 1 credit.

Returns company and asn objects. lookup_ip returns the same data plus location, timezone, and more. Use this when the company/ASN pair is all you need and you want a smaller response.

Parameter	Required	Description
ip		IP address
force_refresh		Skip the cache

13. lookup_currency

Currency, country calling code, TLD, and languages for one IP. Free and paid. 1 credit.

Returns currency and country_metadata objects.

Parameter	Required	Description
ip		IP address
force_refresh		Skip the cache

14. lookup_network

Route prefix, connection type, and anycast status for one IP. Paid. 1 credit.

Returns a network object with connection_type , route , and is_anycast .

Parameter	Required	Description
ip		IP address
force_refresh		Skip the cache

15. lookup_asn

Full ASN lookup. Paid. 1 credit.

lookup_ip also returns an asn object, but only with basic metadata. This tool returns the full ASN record, including peers, upstreams, downstreams, routes, and WHOIS. Call it once with the include fields you need, then filter locally instead of making multiple calls for different slices.

Parameter	Required	Description
asn		ASN (e.g., AS13335 or 13335 )
ip		IP address to resolve to an ASN
include		peers , downstreams , upstreams , routes , whois_response
fields		Comma-separated fields to return
excludes		Comma-separated fields to exclude
force_refresh		Skip the cache

16. get_abuse_contact

Abuse contact details for one IP. Paid. 1 credit.

Returns the abuse route, country, contact name, organization, address, email addresses, and phone numbers. If you also need geolocation or security data for the same IP, use lookup_ip with include=abuse (or include=security,abuse ) to get everything in one call.

Parameter	Required	Description
ip		IP address
fields		Comma-separated fields to return
excludes		Comma-separated fields to exclude
force_refresh		Skip the cache

1. Check if an IP is safe

• Is 49.12.212.42 safe to trust in our network? Give me the threat summary and city.
• Check these IPs for VPN, proxy, Tor, bot, and spam indicators: 49.12.212.42, 2.56.12.11, 8.8.8.8
• For 203.0.113.42, tell me the threat score, whether it is a cloud provider, and whether it looks like a relay.

2. Find who owns an IP

• Who uses 1.1.1.1 and which ASN routes it?
• For AS24940, list upstream ASN numbers only.
• Is this IP anycast and what route prefix is announced for it: 1.1.1.1

3. Get abuse contacts

• For IP 2.56.12.11, give me the abuse contact email, phone number, and organization.
• I need the abuse contact for 1.0.0.0 and the network route involved.
• For this IP, show me the abuse contact details only: 198.51.100.27

4. Timezone lookups and conversions

• What time is it in Tokyo right now?
• Convert 2026-03-07 09:30 from New York to Tokyo time.
• What is the current local time at JFK airport?

5. Sunrise, sunset, and moon data

• Give sunrise and sunset for London on 2026-06-21.
• Show sunrise times in Karachi from 2026-03-10 to 2026-03-15.
• For New York, give me moon phase and day length on 2026-07-17.

6. Parse user-agent strings

• Parse this user agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9
• Parse these user agents in bulk and tell me the browser, OS, and device type for each.
• Does this user agent look like a crawler or bot? Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; + http://www.google.com/bot.html)