IPGeolocation.io MCP Server

Overview

Use the official 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 for configuration examples.

This README describes 2.0.1. The npx commands and Cursor install link below install the latest published npm package. See the changelog for changes to pagination, limits, and error handling.

Quick Start

1. Create a free IPGeolocation 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.

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}

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

Verify It Works

Try these after setup:

Tools by Plan

Version 2.0.1 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 upstream requests. Cache hits and cached-page reads use no additional credits. The API's X-Credits-Charged response header establishes actual billing; see the credit rules.

Tool Reference

Tool arguments must match the advertised schema. Unknown parameters are rejected locally before any API request, so a misspelled selector cannot silently look up the server's IP.

Coordinates, including conversion selectors, and elevation take string values, such as "24.86" and "10" . force_refresh takes a boolean.

---

1. lookup_ip

Single IP or domain lookup through the IP Geolocation API. Free and paid. 1 credit for base IP data.

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.

Fields enable the optional modules they need. These modules require a paid plan:

Selected field	Enabled module
security.is_vpn	security
location.accuracy_radius , location.confidence , or location.locality	geo_accuracy
location.dma_code	dma_code

Accuracy and DMA values appear inside location . An explicit include keeps its module present even if fields omits it. You can exclude nested fields, but a root named by fields or an explicit include stays present. include=* follows field selection and exclusions without protecting those roots. Cached results follow the same rules as fresh responses.

---

2. bulk_lookup_ip

Batch IP lookup. Paid. 1 credit per IP.

Takes an array of IPs or domains (up to 250 by default). The batch limit is the lower of IPGEOLOCATION_MCP_MAX_BULK_ITEMS and IPGEOLOCATION_MCP_MAX_RESULT_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

---

4. check_security

Threat and anonymity data for one IP through the IP Security API. 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 or ASN, use lookup_ip with include=security to get them in one request. It costs 3 credits, the same as a separate security check and base lookup. Add abuse to include when abuse contacts are also needed.

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. Accepts up to 250 inputs by default, subject to the same bulk limits as bulk_lookup_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 through the Time Zone API. 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.

With no selector, the API uses the server machine's public egress IP, which can differ from your IP.

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.

Provide one source selector and one destination selector using an IANA time zone, coordinates, a city/address, an airport code, or a UN/LOCODE. If you omit time , the API converts the current time. This tool does not accept IP selectors or lang and always calls the API (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 through the Astronomy API. 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).

This tool always calls the API, including when date is set; it does not use the response cache.

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 through the User-Agent API. 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 250 strings per request by default. The batch limit is the lower of IPGEOLOCATION_MCP_MAX_BULK_ITEMS and IPGEOLOCATION_MCP_MAX_RESULT_ITEMS .

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

---

12. lookup_company

Company details and ASN ownership for one IP. Company details require paid; free plans return basic ASN only. 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 . If the API omits network data, the tool returns a local error instead of an empty success. This does not invent an upstream HTTP status, and the API call may already have consumed credits.

Parameter	Required	Description
ip		IP address
force_refresh		Skip the cache

---

15. lookup_asn

Network allocation and relationship data through the ASN API. Paid. 1 credit.

Use this tool for ASN details and optional peers, upstreams, downstreams, routes, and WHOIS datasets. Request the datasets you need with include , then filter the cached result to retrieve different slices. lookup_ip also provides ASN metadata as part of an IP lookup.

fields automatically enables optional datasets it references, such as upstreams.as_number . excludes alone does not request extra datasets.

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 through the IP Abuse Contact API. 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

---

17. get_cached_result

Read a page from a previous oversized result. Free and paid. 0 credits. Added in 2.0.1.

Parameter	Required	Description
cursor		The previous response's page.cursor to replay it, or page.next_cursor to continue

Use the same server process and API key. Page reads extend the snapshot's idle expiry and never call the API, including on failure. See Cached Result Pagination for the response fields and a complete recovery example.

Prompt Examples

For a paid IP investigation, call lookup_ip once with ip: "49.12.212.42" , include: "security,abuse" , and fields: "location,company,asn,security,abuse" . This combines location, ownership, threat indicators, and abuse contacts for an estimated 4 credits. Describe the evidence and any unknown fields; apply the user's policy before recommending an allow/block decision.

For a mixed batch, call bulk_lookup_ip with ips: ["8.8.8.8", "10.0.0.1", "1.1.1.1"] and fields: "location.country_name" . Inspect structuredContent.errors to identify the private input and use the successful records directly. The two valid IP lookups cost an estimated 2 credits; the private IP is not billed. Split larger batches at the advertised input limit.

An ASN identifies a network that announces IP routes. Anycast lets one IP be served from multiple locations, so its location need not identify the server that handled a particular request. A bogon address is reserved or otherwise not publicly routable. Upstream in an error means the IPGeolocation.io API contacted by this server.

IP location is an estimate. Use include=geo_accuracy where available to assess uncertainty. Threat scores and VPN/proxy flags are signals for investigation, not guarantees of harmless or malicious traffic. Treat missing, null, or unknown indicators as unavailable, not as false . Combine location, ownership, security signals, and abuse contacts with your own allow/block policy.

Example Answers and Tool Output

The text answers below are illustrative; exact wording depends on the model. JSON blocks are shortened examples, not current measurements. Location, ownership, contacts, and current-time fields can change.

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "country_name": "Sweden",
5    "state_prov": "Stockholms lan",
6    "city": "Stockholm"
7  },
8  "asn": {
9    "as_number": "AS1257",
10    "organization": "Tele2 Sverige AB",
11    "country": "SE"
12  },
13  "time_zone": {
14    "name": "Europe/Stockholm",
15    "current_time": "2026-02-12 18:36:54.401+0100"
16  }
17}

1{
2  "original_time": "2025-01-21 13:42:52",
3  "converted_time": "2025-01-21 09:42:52",
4  "diff_hour": 4,
5  "diff_min": 240
6}

1{
2  "ip": "1.0.0.0",
3  "abuse": {
4    "route": "1.0.0.0/24",
5    "country": "AU",
6    "name": "IRT-APNICRANDNET-AU",
7    "address": "PO Box 3646, South Brisbane, QLD 4101, Australia",
8    "emails": ["helpdesk@apnic.net"]
9  }
10}

Error Codes

Tool failures return isError: true , readable text, and structuredContent.error with a redacted, length-limited message, category, retryability, and guidance:

Input validation uses the registered Zod schemas and the same structured error envelope as execution failures. Unknown tools and malformed MCP requests produce protocol errors. Retry guidance does not guarantee that a retry will succeed or be free: a local timeout can happen after the API processed a paid request. HTTP 429 is a credit/subscription limit, so immediate automatic retries are disabled; retry after credits become available.

The following table applies to HTTP errors actually received from the API:

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.

Bulk text preserves the API's per-item format. Structured results contain items in input order plus an errors list. Each failed item includes its zero-based input_index , original input , source, category, message, retryability, and guidance. An item status is present only if supplied by the API; message-only errors do not acquire an invented HTTP status. A mismatched result count returns a whole-call error rather than assigning unreliable input identifiers. Inspect every record; overall request success does not establish that every item succeeded, and successful items should not be retried.

How It Works

Your MCP client uses this server to call the IPGeolocation.io v3 APIs.

At runtime:

1. Your MCP client starts the server process.
2. The client reads the tool list.
3. When a prompt matches a tool, the client calls it.
4. The server validates arguments and returns a cached result or calls the API. It returns text content plus structuredContent ; all 17 tools advertise an output schema.

Normal text responses keep the API's JSON format, or a plain IP string for get_my_ip . Oversized successful responses contain a page in both text and structured content.

Authenticated upstream requests send the API key in the x-ipgeolocation-api-key header. The key is not added to request URLs.

Server instructions and tool descriptions explain selection, costs, limits, and interpretation to the MCP client. Clients decide how to expose this guidance to their assistant. Returned WHOIS text, user agents, hostnames, and error messages are untrusted data and must not override those instructions. An omitted IP selector refers to the server machine's public egress IP, which can differ from the end user's IP. Security tools query IP intelligence; they do not invoke the separate browser-based live VPN/proxy detection API.

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

The server stores cached responses in process memory and shares identical requests already running for the same API key. Sessions using the same key share the cache namespace; different keys use separate namespaces.

Cached data	Default expiry	Reads extend expiry?
Normal tool response	5 minutes after storage
Complete pagination snapshot	5 minutes of idle time	Yes, after each successful get_cached_result read

Both use IPGEOLOCATION_MCP_CACHE_TTL_MS ( 300000 ms by default). The cache holds up to 500 entries by default, shared by normal responses and page snapshots. This limits entry count, not total bytes or memory. A complete snapshot can be much larger than an individual page.

Expiry, eviction, or process restart can make cached data unavailable. get_cached_result then fails locally without refetching. Repeating the original lookup after a cache miss can consume credits again.

force_refresh: true starts a new upstream request, even if an identical request is running. Older requests cannot overwrite its cached result.

Cached: lookup_ip , bulk_lookup_ip , check_security , bulk_security_check , lookup_company , lookup_currency , lookup_network , parse_user_agent , bulk_parse_user_agent , lookup_asn , get_abuse_contact , get_astronomy_time_series

Always live (not cached): get_my_ip , get_timezone , convert_timezone , get_astronomy

Environment Variables

Variable	Required	Default	Description
IPGEOLOCATION_API_KEY	Yes (most tools)		Your ipgeolocation.io API key
IPGEOLOCATION_REQUEST_TIMEOUT_MS		15000	Upstream deadline in ms, including response-body reading. Range: 1000-120000
IPGEOLOCATION_MCP_CACHE_TTL_MS		300000	Normal-response TTL and page-snapshot idle TTL in ms. Range: 1000-3600000
IPGEOLOCATION_MCP_CACHE_MAX_ENTRIES		500	Maximum cached responses and page snapshots; not a memory-byte limit. Range: 10-5000
IPGEOLOCATION_MCP_MAX_BULK_ITEMS		1000	Bulk input ceiling, also capped by IPGEOLOCATION_MCP_MAX_RESULT_ITEMS . Max: 50000
IPGEOLOCATION_MCP_MAX_RESULT_ITEMS		250	Bulk input/result item ceiling; nested arrays remain complete. Max: 50000
IPGEOLOCATION_MCP_MAX_RESPONSE_CHARS		200000	Maximum UTF-8 bytes of a complete serialized tool result, including text and structured content. Oversized successes use cached pages; oversized errors shorten messages. Range: 10000-2000000
IPGEOLOCATION_MCP_MAX_ERROR_CHARS		4000	Upper limit on error-message characters before truncation markers. The complete response byte budget can shorten messages further. Range: 200-50000

Bulk batches above the effective item limit are rejected before an upstream request, without using API credits. Raising only IPGEOLOCATION_MCP_MAX_BULK_ITEMS does not raise the effective limit; raise both item settings if larger batches are needed.

The response limit includes both text and structured content, JSON escaping, and UTF-8 encoding. Successful results retain every record and nested array through cached pages when needed. Oversized errors shorten only their messages, preserving their category, retryability, guidance, and any status.

Cached Result Pagination

get_cached_result costs 0 credits and never calls the API, including when its cursor is invalid, expired, evicted, or unavailable after a server restart. It accepts one required cursor , returned in page.cursor or page.next_cursor . Use the same server process and API key.

A large original lookup returns { "page": ... } instead of its normal data or items / errors . Each page contains:

Read each next_cursor with get_cached_result , concatenate the json_fragment strings in offset order, and parse the joined JSON once. A fragment is not necessarily valid JSON on its own. This also handles a single record or string larger than one page. Bulk results reconstruct the complete { "items": [...], "errors": [...] } , preserving input identifiers and statuses. Single lookups reconstruct { "data": ... } .

let response = await client.callTool({ name: "bulk_lookup_ip", arguments: { ips } });
if (response.isError) throw new Error(response.content[0].text);
let complete = response.structuredContent;
if (complete.page) {
  let json = "";
  for (;;) {
    const page = response.structuredContent.page;
    json += page.json_fragment;
    if (!page.next_cursor) break;
    response = await client.callTool({
      name: "get_cached_result", arguments: { cursor: page.next_cursor }
    });
    if (response.isError) throw new Error(response.content[0].text);
  }
  complete = JSON.parse(json);
}

Use cursors to retrieve remaining data. The cache rules explain snapshot expiry, eviction, API-key isolation, and when a new lookup can consume credits.

Building from Source

git clone https://github.com/IPGeolocation/ipgeolocation-io-mcp.git
cd ipgeolocation-io-mcp
npm ci --ignore-scripts
npm run build

Run it directly:

node dist/cli.js

Set IPGEOLOCATION_API_KEY through your shell's private environment settings before running the command. The process waits for MCP messages on stdin; it does not display an interactive prompt.

Inspect with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/cli.js

Docker

docker build -t ipgeolocation-mcp .
docker run --rm -i -e IPGEOLOCATION_API_KEY ipgeolocation-mcp

Set IPGEOLOCATION_API_KEY in your private shell environment first. The image includes Node.js and runs as the unprivileged node user. Docker's -i flag keeps stdin open for MCP messages. Omit -t so the protocol uses ordinary stdin/stdout.

The final image runs the compiled server directly. npm and Yarn are available in the build stage; the runtime image contains Node.js and the installed production dependencies.

After building the image, configure a local-command MCP client with:

1{
2  "mcpServers": {
3    "ipgeolocation": {
4      "command": "docker",
5      "args": ["run", "--rm", "-i", "-e", "IPGEOLOCATION_API_KEY", "ipgeolocation-mcp"],
6      "env": {
7        "IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
8      }
9    }
10  }
11}

Testing

Client setup examples document configuration formats. Record GUI and operating-system installation checks separately from protocol, package, and Docker tests; see the release checklist.

npm test               # full suite
npm run test:unit      # unit tests only
npm run test:integration  # integration tests only

Live smoke tests use a real stdio MCP client and spend API credits. IPGEOLOCATION_FREE_KEY with npm run test:live:free checks the seven core tools, paid-feature restrictions, ownership/network fallbacks, and the observed bulk entitlement. It reports when bulk access differs from the documented paid-only policy. IPGEOLOCATION_PAID_KEY with npm run test:live:paid checks all 16 API tools, paid modules, structured validation errors, mixed valid/private bulk inputs, and the local cached-result reader. Testing a paid key does not verify free-plan entitlement restrictions.

After building, verify complete cached pagination with either key:

node tests/pagination.stdio.mjs free  # uses IPGEOLOCATION_FREE_KEY
node tests/pagination.stdio.mjs paid  # uses IPGEOLOCATION_PAID_KEY

Each run makes one six-IP API request and checks the reported six credits. It compares the recovered records against a hash of the complete upstream response and verifies that page reads, replay, expiry, and process restart make no additional API calls. The test temporarily lowers the child server's response budget and cache TTL; your server configuration stays unchanged.

To check the same behavior in the image built above:

node tests/pagination.stdio.mjs free docker run --rm -i \
  -e IPGEOLOCATION_API_KEY -e IPGEOLOCATION_MCP_MAX_RESPONSE_CHARS \
  -e IPGEOLOCATION_MCP_CACHE_TTL_MS -e NODE_OPTIONS ipgeolocation-mcp

Troubleshooting

Client uses an old tool after updating: Restart the server process and check its version in your client's MCP connection details. Compare it with the latest npm version. Rebuild source and Docker installations before restarting them.

API key not configured: Set IPGEOLOCATION_API_KEY in your client's server configuration. This local error has no HTTP status and makes no upstream request.

401 errors: The API rejected the key or requested capability. Check that the key is active and the plan supports the tool. Domain lookups in lookup_ip also require a paid plan.

423 errors: Use a public routable IP. Private/bogon addresses such as 10.0.0.1 and reserved documentation addresses such as 203.0.113.42 cannot be used as successful geolocation examples.

Local 504 timeouts: With source: "mcp_server" , the request or response-body read exceeded the deadline. Check the connection or increase IPGEOLOCATION_REQUEST_TIMEOUT_MS (default: 15000 ms, max: 120000 ms). With source: "ipgeolocation_api" , 504 is an HTTP response from the API.

Redirect blocked: The server received an unexpected HTTP redirect and stopped before forwarding credentials or request data. Do not retry automatically. Investigate the API endpoint or contact support with the sanitized error.

Cached result unavailable: The cursor belongs to another key or process, or the snapshot expired or was evicted. The failed page read made no API call. A new lookup can consume credits.

Client asks for an MCP URL: This package supplies a local stdio command. Use a client or host that can launch it; a remote-only connector needs a hosted MCP endpoint.

Pricing

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

Links

• IPGeolocation Website
• IPGeolocation API Documentation
• IPGeolocation Pricing
• Create a Free IPGeolocation API Key
• Changelog
• Security Policy
• Contributing
• Release Checklist

License

MIT

Privacy Policy

API lookups send the requested inputs to IPGeolocation.io, which also receives the server machine's public egress IP. The server caches results in process memory. Your MCP client or hosting provider controls its own configuration and log storage. See the Security Policy for retention details and the IPGeolocation Privacy Policy for provider handling.