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 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.
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.
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)
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 *
fields
No
Comma-separated fields to return
excludes
No
Comma-separated fields to exclude
force_refresh
No
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.
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
Yes
Array of IP addresses or domains
lang
No
Response language
include
No
Extra modules per IP
fields
No
Comma-separated fields to return per IP
excludes
No
Comma-separated fields to exclude per IP
force_refresh
No
Skip the cache
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.
check_security
Threat and anonymity data for one IP. Paid. 2 credits.
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
No
IP address to check
fields
No
Comma-separated fields to return
excludes
No
Comma-separated fields to exclude
force_refresh
No
Skip the cache
bulk_security_check
Batch version of check_security. Paid. 2 credits per IP.
Parameter
Required
Description
ips
Yes
Array of IP addresses
fields
No
Comma-separated fields to return per IP
excludes
No
Comma-separated fields to exclude per IP
force_refresh
No
Skip the cache
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
No
IANA timezone name (e.g., America/New_York)
lat + long
No
Latitude and longitude
location
No
City or address string
ip
No
IP address
iata_code
No
IATA airport code
icao_code
No
ICAO airport code
lo_code
No
UN/LOCODE
lang
No
Response language. Non-English requires a paid plan.
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
No
yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss. Defaults to now.
tz_from / tz_to
No
IANA timezone names
lat_from + long_from
No
Source coordinates
lat_to + long_to
No
Destination coordinates
location_from / location_to
No
City/address strings
iata_from / iata_to
No
IATA airport codes
icao_from / icao_to
No
ICAO airport codes
locode_from / locode_to
No
UN/LOCODEs
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
No
Coordinates (highest priority when given)
location
No
City or address
ip
No
IP address
date
No
YYYY-MM-DD. Defaults to today.
elevation
No
Meters, 0 to 10000
time_zone
No
IANA name to control output times
lang
No
Response language. Non-English requires a paid plan.
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
Yes
Start date (YYYY-MM-DD)
dateEnd
Yes
End date (YYYY-MM-DD). Max span: 90 days.
lat + long
No
Coordinates (highest priority when given)
location
No
City or address
ip
No
IP address
elevation
No
Meters
time_zone
No
IANA name to control output times
lang
No
Response language. Non-English requires a paid plan.
force_refresh
No
Skip the cache
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
Yes
The user-agent string to parse
force_refresh
No
Skip the cache
Returns name, type, version, device, engine, and operating_system.
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
Yes
Array of user-agent strings
force_refresh
No
Skip the cache
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
No
IP address
force_refresh
No
Skip the cache
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
No
IP address
force_refresh
No
Skip the cache
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
No
IP address
force_refresh
No
Skip the cache
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.
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
No
IP address
fields
No
Comma-separated fields to return
excludes
No
Comma-separated fields to exclude
force_refresh
No
Skip the cache
Prompt Examples
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.
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
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
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?
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.
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)
Example Answers and Tool Output
The text answers below show what a client might say. Exact wording depends on the model. The JSON blocks show raw tool output, trimmed for readability.
Single IP lookup
Prompt: Locate 91.128.103.196 and give me the country, city, ASN, and local time.
Example answer: 91.128.103.196 is in Stockholm, Sweden. ASN is AS1257, operated by Tele2 Sverige AB. Timezone is Europe/Stockholm, local time was 2026-02-12 18:36:54.
json
{"ip":"91.128.103.196","location":{"country_name":"Sweden","state_prov":"Stockholms lan","city":"Stockholm"},"asn":{"as_number":"AS1257","organization":"Tele2 Sverige AB","country":"SE"},"time_zone":{"name":"Europe/Stockholm","current_time":"2026-02-12 18:36:54.401+0100"}}
Time conversion
Prompt: Convert 2025-01-21 13:42:52 from DXB to LHR.
Example answer: 2025-01-21 13:42:52 in Dubai converts to 2025-01-21 09:42:52 in London. The difference is 4 hours.
Example answer: The abuse contact for 1.0.0.0 is IRT-APNICRANDNET-AU in Australia, covering route 1.0.0.0/24. Email: helpdesk@apnic.net.
json
{"ip":"1.0.0.0","abuse":{"route":"1.0.0.0/24","country":"AU","name":"IRT-APNICRANDNET-AU","address":"PO Box 3646, South Brisbane, QLD 4101, Australia","emails":["helpdesk@apnic.net"]}}
Error Codes
All tools return structured errors instead of crashing the server. API errors include the upstream status/message plus a guidance field so MCP clients can tell the user what to check next instead of only repeating the upstream response.
Code
Meaning
400
Bad parameters, invalid date/time format, missing coordinate pair, or unsupported input
401
Missing/invalid API key, free plan calling a paid tool, or non-English lang on free plan
404
Resource not found (e.g., ASN does not exist)
405
Method or subscription restriction from the upstream API
413
POST body is larger than the upstream API allows
415
POST request is missing the required application/json content type
423
Bogon or private IP (10.x.x.x, 192.168.x.x, etc.)
429
Daily request limit (free plan) or subscription/surcharge quota exceeded
499
Client-side request or connection timeout was too short
5xx
Upstream API server-side error
502
Server could not reach the upstream API
504
Upstream API timed out
Exact status codes can vary by endpoint and request mode. If an upstream endpoint returns a status outside this table, the server does not guess the cause. It passes the upstream status and message through with category: "undocumented_api_error" and adds guidance for the MCP client to explain the response as an undocumented upstream status without inventing a cause.
How It Works
This is a stdio MCP server that wraps the ipgeolocation.io v3 APIs.
At runtime:
Your MCP client starts the server process.
The client reads the tool list.
When a prompt matches a tool, the client calls it.
The server validates inputs, calls our API, and returns structured JSON.
Cacheable responses are stored in process memory so repeated identical requests skip the API call.
Authenticated upstream requests send the API key in the x-ipgeolocation-api-key header. The key is not added to request URLs.
lookup_company, lookup_currency, and lookup_network are wrappers around parts of the full IP lookup response. They exist as separate tools so MCP clients can discover them when a user only needs one piece of data.
Caching
Tools that return stable data (not current-time lookups) cache their responses in process memory. Repeated lookups are faster and don't use additional credits. Client retries don't generate duplicate API calls.
Process-level cache, not client or model memory
Cache entries are scoped by API key, so separate MCP sessions do not share cached upstream data
Default TTL: 5 minutes (300000 ms)
Cache resets when the server process stops
Cache misses on TTL expiry, changed parameters, or force_refresh: true
docker build -t ipgeolocation-mcp .
docker run -e IPGEOLOCATION_API_KEY=<YOUR_KEY> ipgeolocation-mcp
Testing
bash
npm test# full suite
npm run test:unit # unit tests only
npm run test:integration # integration tests only
Troubleshooting
Client uses an old tool after updating: Restart the client and confirm it loaded the latest npm version.
401 errors: Check that IPGEOLOCATION_API_KEY is set in your config. Some tools are paid-only and return 401 on the free plan. Domain lookups in lookup_ip also require a paid plan.
423 errors: You passed a private/bogon IP like 10.0.0.1 or 192.168.1.1. These have no geolocation data.
504 timeouts: The upstream API did not respond in time. Increase the timeout with IPGEOLOCATION_REQUEST_TIMEOUT_MS (default: 15000 ms, max: 120000 ms).
