Ipgeolocation Io Mcp

IPGeolocation.io MCP Server

[](https://safeskill.dev/scan/ipgeolocation-io-mcp)

[](https://www.npmjs.com/package/ipgeolocation-io-mcp) [](https://github.com/IPGeolocation/ipgeolocation-io-mcp/releases) [](https://registry.modelcontextprotocol.io/?q=ipgeolocation) [](https://glama.ai/mcp/servers/IPGeolocation/ipgeolocation-io-mcp) [](https://nodejs.org/) [](https://github.com/IPGeolocation/ipgeolocation-io-mcp/blob/main/LICENSE)

Official MCP server for IPGeolocation.io. Includes 16 MCP tools: IP geolocation, threat/VPN/proxy detection, timezone lookups and conversions, sunrise/sunset/moon data, ASN details, abuse contacts, and user-agent parsing. Seven tools work on the free plan (1,000 credits/day). Paid plans unlock all 16 plus bulk endpoints (up to 1,000 items per call).

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

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

Quick Start

1. Create a free IPGeolocation API key

1. Cursor users can install in one click:

[](https://cursor.com/en/install-mcp?name=ipgeolocation&config=eyJjb21tYW5kIjoibnB4IC15IGlwZ2VvbG9jYXRpb24taW8tbWNwIiwiZW52Ijp7IklQR0VPTE9DQVRJT05fQVBJX0tFWSI6IiJ9fQ%3D%3D)

1. Add this to your MCP client config (see [Install by Client](#install-by-client) below for the exact config file path for your client):

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

1. Restart your client.

1. Test it: ask "Where is 8.8.8.8 located?"

Table of Contents

• [Quick Start](#quick-start)
• [Install by Client](#install-by-client)
• [Verify It Works](#verify-it-works)
• [Tools by Plan](#tools-by-plan)
• [Tool Reference](#tool-reference)
• [Prompt Examples](#prompt-examples)
• [Example Answers and Tool Output](#example-answers-and-tool-output)
• [Error Codes](#error-codes)
• [How It Works](#how-it-works)
• [Caching](#caching)
• [Environment Variables](#environment-variables)
• [Building from Source](#building-from-source)
• [Docker](#docker)
• [Testing](#testing)
• [Troubleshooting](#troubleshooting)
• [Pricing](#pricing)
• [Links](#links)
• [License](#license)
• [Privacy Policy](#privacy-policy)

Install by Client

Requirements

• Node.js 18 or later
• npx available in your terminal
• An IPGeolocation.io API key for most tools

get_my_ip works without an API key. Everything else requires one.

Sign up for a free IPGeolocation API key

Codex CLI

codex mcp add ipgeolocation --env IPGEOLOCATION_API_KEY= -- npx -y ipgeolocation-io-mcp
codex mcp list

Start a new Codex session after adding the server.

Claude Desktop

Add to claude_desktop_config.json:

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

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

Cline

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

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

Restart Cline after saving.

Cursor

One-click install:

[](https://cursor.com/install-mcp?name=ipgeolocation&config=eyJjb21tYW5kIjoibnB4IC15IGlwZ2VvbG9jYXRpb24taW8tbWNwIiwiZW52Ijp7IklQR0VPTE9DQVRJT05fQVBJX0tFWSI6IiJ9fQ%3D%3D)

Or add to .cursor/mcp.json manually:

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

Restart Cursor after saving.

Windsurf

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

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

Restart Windsurf after saving.

VS Code / GitHub Copilot

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "ipgeolocation": {
        "command": "npx",
        "args": ["-y", "ipgeolocation-io-mcp"],
        "env": {
          "IPGEOLOCATION_API_KEY": ""
        }
      }
    }
  }
}

Restart VS Code after saving.

Glama

You can try the server on Glama directly. Only IPGEOLOCATION_API_KEY is required. Leave other environment variable fields empty unless you want to change cache, timeout, or output limits.

If you don't have a key yet, create a free IPGeolocation API key.

Any Other MCP Client

Use this config:

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

Verify It Works

Try these after setup:

| Prompt | Expected tool | |--------|---------------| | Where is 8.8.8.8 located? | lookup_ip | | For IP 49.12.212.42, give me security verdict, company, ASN, and city. | lookup_ip with fields and include=security | | Is 2.56.12.11 safe to allow and what is the abuse contact email? | lookup_ip with include=security,abuse | | For AS1, list upstream ASN numbers only. | lookup_asn with include=upstreams | | Convert 2026-03-07 09:30 from New York to Tokyo time. | convert_timezone | | Give sunrise times for Karachi from 2026-03-10 to 2026-03-15. | get_astronomy_time_series | | Parse this user agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 | parse_user_agent |

Tools by Plan

Free Plan

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

| Tool | Credits | What it does | |------|---------|--------------| | lookup_ip | 1 | Location, timezone, currency, ASN for one IP | | get_my_ip | 0 | Public IP of the machine running the server | | lookup_currency | 1 | Currency and country metadata for one IP | | get_timezone | 1 | Timezone by name, location, IP, airport code, or UN/LOCODE | | convert_timezone | 1 | Convert time between two locations | | get_astronomy | 1 | Sunrise, sunset, moonrise, moonset, twilight, moon phase for one date | | get_astronomy_time_series | 1 | Daily astronomy data for a date range (up to 90 days) |

Paid Plans

All 16 tools. Paid plans also add network, company, and extended asn fields to lookup_ip, plus the include parameter for security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or *.

| Tool | Credits | What it does | |------|---------|--------------| | bulk_lookup_ip | 1 per IP | Batch geolocation for up to 1,000 IPs | | check_security | 2 | VPN, proxy, Tor, bot, spam, and threat flags | | bulk_security_check | 2 per IP | Batch threat checks | | lookup_company | 1 | Company name and ASN holder for one IP | | lookup_network | 1 | Route prefix, connection type, anycast status | | parse_user_agent | 1 | Parse one UA string into browser, device, OS, engine | | bulk_parse_user_agent | 1 per UA | Batch UA parsing for up to 1,000 strings | | lookup_asn | 1 | ASN details, peers, upstreams, downstreams, routes, WHOIS | | get_abuse_contact | 1 | Abuse contact emails, phone, address, route |

Credit math for lookup_ip with include:

| Combination | Total credits | |-------------|---------------| | Base lookup | 1 | | include=security | 3 | | include=abuse | 2 | | include=* | 4 | | include=security&fields=security | 2 | | include=abuse&fields=abuse | 1 |

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

Tool Reference

lookup_ip

Single IP or domain lookup. Free and paid. 1 credit.

Use this when you need location, timezone, currency, or ASN for one IP address. On paid plans you can add include modules to pull security, abuse, or hostname data in the same call, which avoids extra requests.

Free plan returns base location, country metadata, currency, timezone, and basic ASN. Paid plans add network, company, extended ASN, and the include parameter. Note that domain lookups require a paid plan.

| Parameter | Required | Description | |-----------|----------|-------------| | ip | No | IPv4, IPv6, or domain. Domain lookup requires a paid plan. | | lang | No | Response language. Non-English requires a paid plan. | | include | No | Extra modules: security, abuse, hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or * | | 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.

bulklookupip

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 |

getmyip

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.

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

bulksecuritycheck

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

getastronomytime_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 |

parseuseragent

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.

bulkparseuser_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 wh

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IPGeolocation
• Source: IPGeolocation/ipgeolocation-io-mcp
• License: MIT
• Homepage: https://ipgeolocation.io

Install and usage instructions live in the source repository linked above.