IPGeolocation MCP Server
IPGeolocation MCP server gives an AI assistant 17 tools for IP intelligence, time zones, astronomy, and user-agent parsing (16 on the hosted version, which omits get_my_ip).
IP geolocation —
lookup_ipreturns location, company, ASN, network, time zone, currency, security, abuse, hostname, and user-agent modules for an IP or domain, withfields/includes/excludesto shape and lower credit cost.Bulk IP lookups —
bulk_lookup_ipprocesses up to 250 IPs per request.Server's own IP —
get_my_ipreturns the public IP of the machine running the server (free, local only).Ownership —
lookup_companyreturns company/organization details and ASN ownership.Currency & country metadata —
lookup_currencyreturns currency code/name/symbol plus calling code, TLD, and languages.Network & routing —
lookup_networkreturns route prefix, connection type, and anycast status.Threat detection —
check_securityandbulk_security_checkflag VPN, proxy, Tor, relay, bot, spam, known attacker, and cloud-provider indicators with threat scores.ASN details —
lookup_asnreturns ASN records, peers, upstreams, downstreams, routes, and WHOIS data.Abuse contacts —
get_abuse_contactreturns reporting emails, phones, address, and route.Time zones —
get_timezonereturns current local time and zone metadata for an IP, place, IANA zone, airport, or UN/LOCODE;convert_timezoneconverts a time between two locations.Astronomy —
get_astronomyreturns sunrise/sunset, moonrise/moonset, twilight, day length, and moon phase for one date/place;get_astronomy_time_seriescovers ranges up to 90 days.User-agent parsing —
parse_user_agentandbulk_parse_user_agentextract browser, engine, OS, and device details from UA strings.Cached pagination —
get_cached_resultreads remaining pages of large results at zero credits without another API call.Plans & caching — free plan covers core lookups; paid adds company, network, security, abuse, and bulk tools; results are cached ~5 minutes and
force_refreshbypasses the cache.
Provides tools to look up timezone information, current local time, and specific airport details using 3-letter IATA airport codes.
IPGeolocation.io MCP Server
The official IPGeolocation.io MCP server provides 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) lets your assistant use these tools. Connect to our hosted server, or run the server on your computer.
Published version: 2.0.3.
The local install commands follow npm's latest tag, including future major releases. Restart your local MCP server to load an update. Source and Docker installations need a rebuild.
The table below describes the published local package.
Item | Value |
Package |
|
Version |
|
Release date | 2026-11-05 |
Transport |
|
Node.js |
|
Hosted MCP
Use our hosted server without installing or running an MCP server on your computer. Your client must support Streamable HTTP and private custom headers.
Use your existing IPGeolocation.io API key, or create a free one.
Add a remote MCP connection with these settings:
Setting | Value |
Server URL |
|
Connection type | Streamable HTTP |
Header name |
|
Header value |
|
Save the connection and ask: "Where is 8.8.8.8 located?"
Replace <YOUR_API_KEY> with your key in your client's private settings. Keep the key out of chat messages, URLs and shared files.
Your existing free or paid plan and API credit rules apply.
Hosted MCP provides 16 tools. get_my_ip is available only locally because a hosted server would return its own IP address. For IP lookups, include the IP you want to check.
See the hosted guide for connection details and instructions for running your own hosted server.
Related MCP server: GeoIP MCP Server
Quick Start
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": "<YOUR_API_KEY>"
}
}
}
}Reload the server or restart your client.
Ask "Where is 8.8.8.8 located?"
Table of Contents
Install by Client
The following instructions run MCP on your computer. To connect to our hosted service, see Hosted MCP.
Requirements
Node.js 22 or later for npm/source installs, or a bundle host with a compatible Node.js runtime
npxavailable for the npm configuration examplesAn 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 listStart 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.jsonWindows:
%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": "<YOUR_API_KEY>"
}
}
}
}Restart Cursor after saving.
Cursor plugin
The ipgeolocation-io-mcp 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 that repository into a new directory under ~/.cursor/plugins/local/, reload Cursor, and open Customize > Plugins.
Local plugin: set
IPGEOLOCATION_API_KEYin 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-mcpAPI 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
For local MCP, use the ipgeolocation entry from Quick Start in your client's configuration format. The client must support launching a local stdio process. To connect to our hosted service, follow Hosted MCP.
Verify It Works
Try these after setup:
Prompt | Expected tool |
Where is 8.8.8.8 located? |
|
For IP 49.12.212.42, give me threat indicators, company, ASN, and city. |
|
Show threat indicators and the abuse contact email for 2.56.12.11. |
|
For AS1, list upstream ASN numbers only. |
|
Convert 2026-03-07 09:30 from New York to Tokyo time. |
|
Give sunrise times for Karachi from 2026-03-10 to 2026-03-15. |
|
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 |
|
Tools by Plan
Local MCP provides 17 tools. Hosted MCP provides 16 and does not include get_my_ip. Both follow your IPGeolocation.io plan and credit rules. 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.
Free Plan
The free plan provides 1,000 API credits per day. The following tools provide their core data on Free; get_cached_result also reads saved pages for 0 credits. get_my_ip is available only locally.
Tool | Credits | What it does |
| 1 | Location, time zone, currency, ASN for one IP |
| 0 | Public IP of the machine running the server |
| 1 | Currency and country metadata for one IP |
| 1 | Time zone by name, location, IP, airport code, or UN/LOCODE |
| 1 | Convert time between two locations |
| 1 | Sunrise, sunset, moonrise, moonset, twilight, moon phase for one date |
| 1 | Daily astronomy data for a date range (up to 90 days) |
Company details, network data, security, abuse contacts and bulk geolocation require a paid plan. lookup_company can return basic ASN ownership on Free, but not company details. On Free, include=* returns base IP data only; it does not unlock paid features. See the API plan documentation for current access rules.
Paid Plans
All 17 tools are available locally, or 16 through hosted MCP, including the zero-credit cached result reader. 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 |
| 1 per IP | Batch geolocation, 250 inputs by default |
| 2 | VPN, proxy, Tor, bot, spam, and threat flags |
| 2 per IP | Batch threat checks |
| 1 | Company name and ASN holder for one IP |
| 1 | Route prefix, connection type, anycast status |
| 1 | Parse one UA string into browser, device, OS, engine |
| 1 per UA | Batch UA parsing, 250 strings by default |
| 1 | ASN details, peers, upstreams, downstreams, routes, WHOIS |
| 1 | Abuse contact emails, phone, address, route |
Credit math for lookup_ip with include:
Combination | Total credits |
Base lookup | 1 |
| 3 |
| 2 |
| 4 |
| 1 |
| 2 |
| 1 |
For current plan details and pricing, see the IPGeolocation.io pricing page.
Tool Reference
The full reference lists parameters and response formats. The tools below are available locally; hosted MCP provides the same tools except get_my_ip.
lookup_ip
IP location, company information, ASN and network data, with optional security and abuse details. Parameters.
bulk_lookup_ip
IP lookups in batches of up to 250 by default. Parameters.
get_my_ip
Available only when running MCP locally. Returns the public IP of the machine running the server. No API key or credits needed. Parameters.
check_security
VPN, proxy, Tor, bot, hosting, spam and other threat indicators for an IP. Parameters.
bulk_security_check
Security checks for a batch of IPs. Parameters.
get_timezone
Current local time and time zone details for a place. Parameters.
convert_timezone
Time conversion between two places. Parameters.
get_astronomy
Sun and moon data for one place and date. Parameters.
get_astronomy_time_series
Daily astronomy data for a date range of up to 90 days. Parameters.
parse_user_agent
Browser, operating system and device details from a supplied user-agent string. Parameters.
bulk_parse_user_agent
User-agent parsing for a batch of supplied strings. Parameters.
lookup_company
Company information and ASN ownership for an IP. Company details require a paid plan. Parameters.
lookup_currency
Currency and country metadata for an IP. Parameters.
lookup_network
Route prefix, connection type and anycast status for an IP. Parameters.
lookup_asn
ASN details, network relationships, routes and WHOIS data. Parameters.
get_abuse_contact
Abuse reporting contacts for an IP. Parameters.
get_cached_result
Remaining pages of a saved result, without another API call or additional credits. Parameters.
Prompt Examples
Ask for the information you need in your own words. Available data and credit use depend on your plan.
IP location is an estimate. Threat scores and VPN/proxy flags are signals to investigate, not a guarantee that traffic is safe or harmful. Missing or unknown values do not mean false.
Inspect IP threat indicators
Show the threat indicators and city for 49.12.212.42 so I can assess it against our network policy.
Check these IPs for VPN, proxy, Tor, bot, and spam indicators: 49.12.212.42, 2.56.12.11, 8.8.8.8
For 49.12.212.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: 1.1.1.1
Time zone 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 examples illustrate the format; lookup data can change.
Single IP lookup
See the IP lookup example.
Time conversion
See the time conversion example.
Abuse contact
See the abuse contact example.
Error Codes
Errors explain what failed and suggest a next step. Start with Troubleshooting for common problems, or see the error reference when handling errors in code.
A failed or canceled request may already have used API credits. Check the error guidance before retrying. For bulk results, retry only eligible failed inputs; successful inputs do not need another lookup.
How It Works
Your MCP client connects to our hosted server or starts the server on your computer. The server checks each request, then returns a cached result or calls the IPGeolocation.io API.
Lookups send the requested inputs to IPGeolocation.io. Cached results stay in memory; your client or host controls its own configuration and logs. See the Security Policy for data handling.
When running locally, tools that allow an omitted IP use the server machine's public IP. That can differ from your own IP. Hosted MCP requires an explicit lookup target, such as an IP address, place or ASN. Security tools return IP intelligence; they do not run the separate browser-based Real-Time Proxy & VPN Detection service.
Caching
Most lookup results are cached for five minutes by default. Reusing a cached result costs no additional API credits. Current-time tools (get_timezone, convert_timezone, get_astronomy) and get_my_ip always call the API.
Saved pages remain available for five minutes after the last successful page read by default. Cached data can also disappear when the cache fills or the server restarts. Reading an unavailable page costs no credits, but repeating the original lookup can use credits again.
force_refresh: true requests fresh data and can use credits. See the cache reference for expiry, shared results and refresh rules.
Environment Variables
For local MCP, set IPGEOLOCATION_API_KEY in your client's private server settings. Leave optional settings unset unless you need to change the defaults. To connect to our hosted service, use the Hosted MCP connection settings.
Setting | Default | Purpose |
| Not set | Your API key; required for all API tools except |
|
| How long to wait for an API response. |
|
| How long to keep lookup results and idle result pages. |
The configuration reference lists all settings, limits and allowed values. Larger limits can require more memory.
Cached Result Pagination
Large results can arrive in pages. The get_cached_result tool reads the remaining pages without another API call or additional credits. It also costs nothing if a page is unavailable.
Keep the same server process and API key while reading pages. Saved pages expire after five minutes without a successful read by default, and the cache can remove them sooner if it fills. If the full result is too large to save, the lookup returns an error without a page cursor; the API may already have used credits.
For client developers, the pagination reference explains the page fields and includes a complete retrieval example.
Building from Source
See Building from Source for build commands and MCP Inspector setup. Source installations run the code in your checkout, including any unreleased changes.
Docker
docker build -t ipgeolocation-mcp .
docker run --rm -i -e IPGEOLOCATION_API_KEY ipgeolocation-mcpSet 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.
Rebuild the image when you update the source or need a newer runtime.
After building the image, configure a local-command MCP client with:
{
"mcpServers": {
"ipgeolocation": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "IPGEOLOCATION_API_KEY", "ipgeolocation-mcp"],
"env": {
"IPGEOLOCATION_API_KEY": "<YOUR_API_KEY>"
}
}
}
}Testing
See Testing for the offline suite and separate live API checks. Live checks can use credits.
Troubleshooting
Instructions to restart the server or change environment variables apply when you run the server yourself. For our hosted service, use the connection settings in your client.
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: For local MCP, set IPGEOLOCATION_API_KEY in your client's private server configuration. For hosted MCP, add the X-IPGeolocation-API-Key header in your client's private connection settings. A missing key is rejected before an API lookup.
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.
Network requires a proxy: See the proxy setup instructions for supported Node.js versions and settings.
Timeout: Check the connection and the error guidance before retrying; the API may already have used credits. If requests need longer, adjust IPGEOLOCATION_REQUEST_TIMEOUT_MS within the allowed range.
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.
Resource limit: Check the error's guidance before trying again. The server rejects oversized tool arguments before making an API request. A response can exceed a limit after the API has used credits. Another lookup can use more credits. Reducing displayed fields does not always reduce the API response size. If you received a page cursor, use get_cached_result to read the remaining data without another API request. Raise limits only when the server has enough memory.
Client asks for an MCP URL: Use the hosted connection. Your client must support Streamable HTTP and private custom headers.
Pricing
For current plan details, credits, and pricing, see the IPGeolocation.io pricing page.
Links
License
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.io Privacy Policy for provider handling.
Available Tools
17 toolsbulk_lookup_ipBulk IP GeolocationARead-only
Read-only bulk IP lookup via POST /v3/ipgeo-bulk. Documented as paid-only; the upstream API determines plan access. Base IP data costs 1 credit per valid IP; security adds 2 and abuse adds 1. Selecting only security costs 2, only abuse costs 1, and security plus abuse without base data costs 3 per valid IP. This MCP server accepts up to 250 IPs per request. Larger batches are rejected before any API call. Complete results within upstream and cache byte limits are returned directly or as cached pages. Cached pages use get_cached_result without another API call or additional credits. An upstream body above its byte limit, or a required pagination snapshot too large to retain, returns a non-retryable resource_limit error with no cursor; the API may already have used credits.
The response covers location data or mixed IP data domains for multiple IPs or domains. Private, bogon, and malformed IPs are not billed. fields, excludes, lang, and include behave like lookup_ip for each item; this server also infers include modules from fields. bulk_security_check provides dedicated security-only batch responses.
Inputs: ips (required), lang, fields, include, +2 more. Returns: page, error, items, errors
bulk_parse_user_agentBulk User-Agent ParserARead-only
Read-only bulk user-agent parsing via POST /v3/user-agent-bulk. Paid only. Cost: 1 credit per successful string. This MCP server accepts up to 250 explicit user-agent strings. Larger batches are rejected before any API call. Complete results within upstream and cache byte limits are returned directly or as cached pages. Cached pages use get_cached_result without another API call or additional credits. An upstream body above its byte limit, or a required pagination snapshot too large to retain, returns a non-retryable resource_limit error with no cursor; the API may already have used credits.
Returns one parsed object per string with user_agent_string, name, type, version, version_major, device, engine, and operating_system. uaStrings must be a non-empty array of exact user-agent strings; empty/null strings are rejected locally before any API call. parse_user_agent handles a single string. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: uaStrings (required), force_refresh. Returns: page, error, items, errors
bulk_security_checkBulk Security CheckARead-only
Read-only bulk security lookup via POST /v3/security-bulk. Paid only. Cost: 2 credits per valid IP. This MCP server accepts up to 250 IPs; private, bogon, and malformed IPs are not billed. Larger batches are rejected before any API call. Complete results within upstream and cache byte limits are returned directly or as cached pages. Cached pages use get_cached_result without another API call or additional credits. An upstream body above its byte limit, or a required pagination snapshot too large to retain, returns a non-retryable resource_limit error with no cursor; the API may already have used credits.
This endpoint is dedicated to security-only batches; bulk_lookup_ip with include=security provides security data together with geolocation or other IP domains. Returns one { ip, security } result per valid IP. fields/excludes accept security.* dot paths per item. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: ips (required), fields, excludes, force_refresh. Returns: page, error, items, errors
check_securityVPN/Proxy/Threat DetectionARead-only
Read-only security lookup via GET /v3/security. Paid only. Cost: 2 credits. This endpoint is dedicated to security and threat data; lookup_ip with include=security provides security data together with location, company, ASN, network, timezone, currency, or abuse.
Returns { ip, security } with threat_score, VPN, proxy, residential proxy, Tor, relay, anonymity, bot, spam, known attacker, and cloud-provider fields; provider names, confidence scores, and last_seen dates appear when available.
fields/excludes accept comma-separated security.* dot paths; ip is always returned. Threat scores and flags are indicators, not a safety guarantee; missing or unknown data is inconclusive. This queries IP intelligence, not the separate live browser detection API. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: ip, fields, excludes, force_refresh. Returns: data, page, error
convert_timezoneTimezone ConversionARead-only
Read-only time conversion via GET /v3/timezone/convert. Works on free and paid plans. Cost: 1 credit. The conversion requires one source selector and one destination selector; get_timezone provides a single place's current time and metadata.
Source/destination selectors are tz_from/tz_to, location_from/location_to, iata_from/iata_to, icao_from/icao_to, locode_from/locode_to, or lat_from+long_from and lat_to+long_to. time is optional and must be yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss. Returns original time, converted time, diff_hour, and diff_min.
Inputs: time, tz_to, lat_to, iata_to, +11 more. Returns: data, page, error
get_abuse_contactAbuse Contact LookupARead-only
Read-only abuse contact lookup via GET /v3/abuse. Paid only. Cost: 1 credit. This endpoint is dedicated to abuse contact data; lookup_ip with include=abuse provides abuse data together with location, security, company, ASN, timezone, network, or currency.
Returns { ip, abuse } with route, country, name, organization, kind, address, emails, and phone_numbers for reporting abuse.
fields/excludes accept comma-separated abuse.* paths such as abuse.emails; ip is always returned. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: ip, fields, excludes, force_refresh. Returns: data, page, error
get_astronomyAstronomy DataARead-only
Read-only single-date astronomy lookup via GET /v3/astronomy. Works on free and paid plans. Cost: 1 credit. This endpoint covers one date or real-time sun/moon position; get_astronomy_time_series provides daily sunrise, moon, and twilight data across a date range.
Returns { location, astronomy } plus ip for IP/server-address lookups. astronomy includes date/current_time, sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon position, distance, status, moon_phase, moon_illumination_percentage, and moon_angle.
Selector priority is lat/long, location, ip, then the server's public egress IP when no selector is provided. lat and long must be provided together; date must be YYYY-MM-DD; elevation is in meters, with a maximum of 10000; negative values are treated as 0. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.
Inputs: ip, lat, date, lang, +4 more. Returns: data, page, error
get_astronomy_time_seriesAstronomy Time SeriesARead-only
Read-only daily astronomy series via GET /v3/astronomy/timeSeries. Works on free and paid plans. Cost: 1 credit per request. This endpoint covers date ranges up to 90 days; get_astronomy provides one-date and real-time sun/moon data.
Returns { location, astronomy: [...] } with one daily item per date containing sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon status, and moon_phase. Selector priority is lat/long, location, ip, then the server's public egress IP when no selector is provided.
dateStart and dateEnd are required YYYY-MM-DD values with a maximum 90-day span. lat and long must be provided together; elevation is in meters, with a maximum of 10000; negative values are treated as 0. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: dateEnd (required), dateStart (required), ip, lat, +6 more. Returns: data, page, error
get_cached_resultRead Cached Result PageARead-only
Returns one page of a previously returned result using page.cursor or page.next_cursor. Costs 0 credits and never calls any upstream API, including on failure. The json_fragment strings concatenate in offset order into the complete original structuredContent JSON, including nested arrays and bulk item errors. The last page has no next_cursor. Cursors are scoped to the same API key and server process. Successful reads extend idle expiry by the configured cache TTL (five minutes by default); eviction or restart can remove a result. An unavailable cursor returns a local error and never starts another paid lookup.
Inputs: cursor (required). Returns: page, error
get_my_ipGet My IP AddressARead-only
Returns the public IP address of the machine running this MCP server via GET /v3/getip. Takes no input parameters and requires no API key, account, or credits. Text content contains the IP address; structuredContent contains { ip }. This is not geolocation data. lookup_ip provides location, company, ASN, network, time zone, currency, security and abuse data.
Inputs: no named parameters. Returns: ip, page, error
get_timezoneTimezone LookupARead-only
Read-only timezone lookup via GET /v3/timezone. Works on free and paid plans. Cost: 1 credit. This endpoint provides current local time and metadata for one place, IP, airport, UN/LOCODE, or IANA timezone; convert_timezone provides source-to-destination conversion.
Returns { time_zone } plus selector context such as location, airport, city, or ip. time_zone includes the zone name, current time, UTC offsets, date/time variants, abbreviations, and DST status/transition fields when available.
Selector priority is tz, lat/long, location, ip, iata_code, icao_code, then lo_code. lat and long must be provided together. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans.
Inputs: ip, tz, lat, lang, +5 more. Returns: data, page, error
lookup_asnASN DetailsARead-only
Read-only ASN enrichment via GET /v3/asn. Paid only. Cost: 1 credit. Queries accept asn or ip, with asn taking priority. The response covers ASN relationships, route prefixes, allocation details, and WHOIS; lookup_ip provides basic ASN data together with geolocation.
Returns { asn } core fields plus included peers, downstreams, upstreams, routes, or whois_response. include accepts those five values. fields/excludes accept full asn.* paths or root-relative paths such as upstreams.as_number. fields automatically enables required optional datasets; excludes alone never requests extra datasets. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: ip, asn, fields, include, +2 more. Returns: data, page, error
lookup_companyCompany/Organization LookupARead-only
Read-only ownership lookup via GET /v3/ipgeo. Company details require a paid plan; free plans return basic ASN ownership only. Cost: 1 credit. This response is limited to company and ASN ownership; lookup_ip can return ownership together with location, security, abuse, network, timezone, or currency.
Returns { company, asn }: company name/type/domain plus ASN allocation fields when available. ip omitted means the server's public egress IP. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
Inputs: ip, force_refresh. Returns: data, page, error
lookup_currencyCurrency and Country MetadataARead-only
Read-only currency and country metadata lookup via GET /v3/ipgeo. Works on free and paid plans. Cost: 1 credit per successful lookup.
Returns { currency, country_metadata }: currency code/name/symbol plus country calling_code, tld, and languages. ip selects the IP used to derive country and currency; omit it for the server machine's public egress IP. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.
This response is limited to currency and country metadata. lookup_ip can return these fields together with other IP data.
Inputs: ip, force_refresh. Returns: data, page, error
lookup_ipIP Geolocation LookupARead-only
Read-only unified IP lookup via GET /v3/ipgeo. Base IP data costs 1 credit; security adds 2 and abuse adds 1. Selecting only security costs 2, only abuse costs 1, and security plus abuse without base data costs 3 credits. The unified response can cover multiple data domains for one IP or domain: location, company, ASN, network, timezone, currency, security, abuse, user_agent, hostname, geo_accuracy, and dma_code.
Returns root IP/domain data plus selected objects such as location, country_metadata, currency, asn, network, company, time_zone, security, abuse, user_agent, or hostname. geo_accuracy adds location.accuracy_radius, location.confidence, and location.locality; dma_code adds location.dma_code. Free plans support core location, country_metadata, currency, time_zone, basic ASN, fields, and excludes; paid plans add domain lookup, company, network, extended ASN, non-English lang, and include modules.
ip omitted means the server's public egress IP. IP location is an estimate, not a precise device position. fields/excludes accept comma-separated dot paths; ip is always returned and unknown excludes do not error. Explicit include tokens keep their modules even when fields omits them; fields can select their nested paths and excludes can remove nested paths. A root requested by an explicit include cannot be excluded as a whole; other roots named by fields can be excluded. include=* follows fields/excludes without this explicit-token protection and returns only plan-entitled data, including core data on Free. The user_agent module describes the server's outbound HTTP User-Agent, not a visitor browser associated with the IP. This server auto-adds include modules referenced by fields, including optional location fields. lookup_asn provides ASN relationships, routes, and WHOIS; check_security and get_abuse_contact provide dedicated security and abuse responses.
Inputs: ip, lang, fields, include, +2 more. Returns: data, page, error
lookup_networkNetwork/Routing InfoARead-only
Read-only network lookup via GET /v3/ipgeo. Network details require a paid plan. Cost: 1 credit. Returns { network } with route CIDR prefix, connection_type, and is_anycast. If the API omits network data, returns a local error without inventing an HTTP status; credits may already have been used.
ip omitted means the server's public egress IP. force_refresh bypasses cached data, makes a new upstream request, and can consume credits. This response is limited to network data; lookup_ip can return network data together with location, company, ASN, timezone, currency, security, or abuse.
Inputs: ip, force_refresh. Returns: data, page, error
parse_user_agentUser-Agent ParserARead-only
Read-only custom user-agent parsing via POST /v3/user-agent. Paid only for POST payload parsing. Cost: 1 credit per successful string. Parses only the explicit uaString value; it cannot read caller headers or transport metadata.
Returns { user_agent_string, name, type, version, version_major, device, engine, operating_system }. Type fields can identify desktop/mobile clients, robots, malformed or scripted strings, anonymized strings, or unknown values. uaString must be the exact non-empty user-agent string; empty/null strings are rejected locally before any API call. force_refresh bypasses cached data, makes a new upstream request, and can consume credits. bulk_parse_user_agent handles multiple strings.
Inputs: uaString (required), force_refresh. Returns: data, page, error
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
The six ipgeo-derived lookups (lookup_ip, lookup_company, lookup_currency, lookup_network, check_security, lookup_asn) all return overlapping slices of the same underlying data, and an agent could reasonably satisfy a request with either the dedicated tool or lookup_ip with an include token. The descriptions do explicitly flag this ('this response is limited to X; lookup_ip can return these together with...') and the single-vs-bulk and single-date-vs-range pairs (parse_user_agent/bulk_parse_user_agent, get_astronomy/get_astronomy_time_series, get_timezone/convert_timezone) are cleanly delineated, which keeps it readable but still overlapping.
All names are snake_case verb_noun, which is readable, but the verb choice is inconsistent for the same operation class: lookup_asn/lookup_network vs check_security vs get_abuse_contact all fetch a per-IP data slice. The bulk_ prefix is also applied inconsistently (bulk_lookup_ip, bulk_security_check, bulk_parse_user_agent) rather than as a parameter or suffix convention.
17 tools is slightly above the comfortable band but justified by the breadth of the upstream API (IP, bulk, ASN, security, abuse, UA, timezone, astronomy) plus the required pagination tool get_cached_result. Each tool maps to a real endpoint or capability, though the dedicated thin wrappers around ipgeo arguably duplicate lookup_ip.
Coverage is broad: single and bulk lookup, security, abuse, ASN/WHOIS, UA parsing, timezone and conversion, astronomy single and series, caching, and egress IP. The main gap is account/plan awareness — a credit-metered API with no tool to check remaining credits or plan entitlements, which agents will need to reason about paid-only endpoints and 401s.
Maintenance
Related MCP Connectors
Official IPinfo MCP Server - IP intelligence tools for AI assistants
Unofficial IPInfo MCP — wraps ipinfo.io (free tier, no auth required for basic usage)
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseAqualityBmaintenanceIP Geolocation MCP server using IP2Location.io API to ease the query of geolocation information.118PythonMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides IP geolocation services using MaxMind's GeoIP2 databases, allowing users to retrieve geographical information for single or multiple IP addresses including country, city, coordinates, and ASN details.GPL 3.0
- AlicenseNot gradedqualityFmaintenanceMCP server for IP geolocation lookups using ipinfo.io, with single, own, and batch queries.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server providing IP address lookup capabilities. Enables AI assistants to fetch details about public IP addresses or the user's current device IP.ISC