IP Geolocation MCP Server | IPGeolocation.io

Official MCP server for IP geolocation, IP security, abuse contacts, ASN, timezone, astronomy, and user-agent parsing.

We build and maintain this server so you can use our APIs from Codex, Claude Desktop, Cursor, Windsurf, VS Code, and other MCP-compatible clients.

Quick Start

Sign up for a free IPGeolocation API key, then add this MCP server to your client:

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

Restart your client after saving the configuration.

Table of Contents

• What We Provide

• Install

• Verify It Works

• Prompt Examples by Use Case

• Example Answers and Tool Output

• Tools by Plan

• Tool Details

• Credit Costs

• Error Handling

• Pricing

• Building from Source

• Testing

• How It Works

• Caching and Refresh

• Environment Variables

• License

• Privacy Policy

• Links

What We Provide

We expose 16 MCP tools across our IP intelligence and location APIs.

What you get:

• Official server maintained by the ipgeolocation.io team

• One MCP package for IP lookup, security checks, timezone, astronomy, ASN, abuse contacts, and user-agent parsing

• Free-plan coverage for core location, timezone, and astronomy workflows

• Bulk tools for IP lookup, security checks, and user-agent parsing

• Tool descriptions written to help clients choose lower-cost and lower-latency request paths

• Server-side caching for deterministic lookups so repeated requests for the same input do not keep hitting upstream APIs

• manifest.json included for clients that support MCP Bundles

Install

Requirements

• Node.js 18 or later

• An ipgeolocation.io API key for most tools

• npx available in your environment

get_my_ip works without an API key. All other tools require one.

Sign up for a free IPGeolocation API key

Install by Client

Codex CLI

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

Start a new Codex session after adding the server.

Claude Desktop

We ship manifest.json for clients that support MCP Bundles. If you want to configure Claude Desktop manually, add this to claude_desktop_config.json:

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

Restart Claude Desktop after saving the config.

Glama

You can try the server in Glama at IP Geolocation MCP Server on Glama.

For normal setup in Glama, only IPGEOLOCATION_API_KEY is required. Leave the other environment variable fields empty unless you explicitly want to tune cache, timeout, or output limits.

If you do not already have a key, sign up for a free IPGeolocation API key.

Cline

Open the MCP Servers panel in Cline, go to Configure, then open Advanced MCP Settings. Add this to cline_mcp_settings.json:

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

Restart Cline after saving the config.

Cursor

Add this to .cursor/mcp.json:

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

Restart Cursor after saving the config.

Windsurf

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

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

Restart Windsurf after saving the config.

VS Code / GitHub Copilot

Add this to your VS Code settings.json:

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

Restart VS Code after saving the config.

Any Other MCP Client

Use the same process configuration:

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

Verify It Works

Use these prompts after installation. They are short, easy to validate, and cover the main tool categories.

If your client keeps using an older tool path after an update, restart the client and make sure it is loading version 1.0.10.

Prompt Examples by Use Case

IP reputation and access decisions

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

Ownership, ASN, and routing

• 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

Abuse and incident response

• 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

Time and timezone workflows

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

Astronomy and daylight planning

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

User-agent analysis

• 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

Actual assistant wording varies by client and model. The natural-language snippets below show a typical answer. The JSON blocks show trimmed tool output returned by our MCP server.

Prompt

Locate 91.128.103.196 and give me the country, city, ASN, and local time.

Typical assistant answer

91.128.103.196 resolves to Stockholm, Sweden. The ASN is AS1257, operated by Tele2 Sverige AB. The local timezone is Europe/Stockholm, and the local time in this sample is 2026-02-12 18:36:54.401+0100.

Example tool output

{
  "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"
  }
}

Prompt

Convert 2025-01-21 13:42:52 from DXB to LHR.

Typical assistant answer

2025-01-21 13:42:52 in Dubai converts to 2025-01-21 09:42:52 in London in this sample. The difference is 4 hours.

Example tool output

{
  "original_time": "2025-01-21 13:42:52",
  "converted_time": "2025-01-21 09:42:52",
  "diff_hour": 4,
  "diff_min": 240
}

Prompt

Who uses 1.1.1.1 and which ASN routes it?

Typical assistant answer

1.1.1.1 is used by APNIC Research and Development, while the ASN routing it is AS13335, operated by Cloudflare, Inc.

Example tool output

{
  "company": {
    "name": "APNIC Research and Development",
    "domain": "apnic.net"
  },
  "asn": {
    "as_number": "AS13335",
    "organization": "Cloudflare, Inc.",
    "country": "US"
  }
}

Prompt

Show sunrise and sunset for New York from 2025-06-16 to 2025-06-18.

Typical assistant answer

For this New York date range, sunrise is about 05:23 and sunset about 20:30 each day. Day length is about 15 hours, and the moon phase changes from waning gibbous to last quarter in this sample.

Example tool output

{
  "location": {
    "country_name": "United States",
    "state_prov": "New York",
    "city": "New York",
    "latitude": "40.76473",
    "longitude": "-74.00084"
  },
  "astronomy": [
    {
      "date": "2025-06-16",
      "sunrise": "05:23",
      "sunset": "20:30",
      "day_length": "15:06",
      "moon_phase": "WANING_GIBBOUS"
    },
    {
      "date": "2025-06-17",
      "sunrise": "05:23",
      "sunset": "20:30",
      "day_length": "15:06",
      "moon_phase": "LAST_QUARTER"
    }
  ]
}

Prompt

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

Typical assistant answer

This user agent is Safari 9.0.2 on Mac OS 10.11.2, running on an Apple Macintosh desktop with an Intel CPU.

Example tool output

{
  "user_agent_string": "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",
  "name": "Safari",
  "type": "Browser",
  "version": "9.0.2",
  "device": {
    "name": "Apple Macintosh",
    "type": "Desktop",
    "brand": "Apple",
    "cpu": "Intel"
  },
  "operating_system": {
    "name": "Mac OS",
    "type": "Desktop",
    "version": "10.11.2"
  }
}

Prompt

Give me the abuse contact for 1.0.0.0.

Typical assistant answer

For 1.0.0.0, the abuse contact in this sample is IRT-APNICRANDNET-AU in Australia, covering route 1.0.0.0/24, with email helpdesk@apnic.net.

Example tool output

{
  "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"]
  }
}

Tools by Plan

Free Plan

The free plan includes 1,000 credits per day and supports these tools:

Paid Plans

Paid plans unlock all tools and additional fields on lookup_ip.

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 Details

Single IP or domain lookup.

Plan: free and paid
Credits: 1 base credit

Choose this when:

• You need geolocation, timezone, currency, or ASN for one IP

• You need both base IP data and extra modules such as security or abuse

• You want one request instead of multiple single-purpose calls

Free plan returns base location, country metadata, currency, timezone, and basic ASN.

Paid plans add network, company, and extended ASN fields. Paid plans also support include modules.

Bulk IP lookup for multiple addresses or domains.

Plan: paid only
Credits: 1 per IP

Choose this when:

• You need geolocation or IP intelligence for more than one IP

• You want one request for a batch instead of many single lookups

The default cap is 1,000 items per MCP request. You can change it with IPGEOLOCATION_MCP_MAX_BULK_ITEMS.

Return the public IP address of the machine running this MCP server.

Plan: free and paid
Credits: 0

Choose this when:

• You need the caller IP only

• You want a no-auth health check for the server connection

Parameters: none

This tool always goes upstream and is not cached.

Threat and anonymity lookup for a single IP.

Plan: paid only
Credits: 2

Choose this when:

• You only need security data for one IP

• You do not need company, ASN, location, or abuse data in the same response

If the same prompt also needs ownership, city, timezone, network, or abuse details, prefer lookup_ip with targeted include, fields, and excludes.

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

Threat and anonymity lookup for multiple IPs.

Plan: paid only
Credits: 2 per IP

Choose this when:

• You need security-only checks for more than one IP

• You are triaging or screening a list of IPs

Current time and timezone details for a location.

Plan: free and paid
Credits: 1

Choose this when:

• You need the current local time and timezone details for one location

• You want timezone data by IANA name, coordinates, IP, airport code, or UN/LOCODE

Returns an object with location and time_zone. The time_zone object includes timezone offsets, date/date_time variants, current_time, current_time_unix, time_24, time_12, week, month, year, timezone abbreviations, and DST transition details.

This tool always goes upstream and is not cached because it returns current time.

Convert a time from one location to another.

Plan: free and paid
Credits: 1

Choose this when:

• You need a converted time between two timezones, locations, coordinates, or airports

• You want a direct time difference instead of two separate timezone lookups

This tool always goes upstream and is not cached because it can default to the current time.

Sun and moon data for one location on one date.

Plan: free and paid
Credits: 1

Choose this when:

• You need sunrise, sunset, moonrise, moonset, or day length for one date

• You need current positional data such as sun altitude or moon azimuth

Returns an object with location and astronomy. The astronomy object includes morning and evening twilight blocks, sunrise/sunset, solar noon, day length, moonrise/moonset, status fields, and the live sun/moon position fields for that date and location.

This tool always goes upstream and is not cached because omitting date returns time-sensitive data.

Astronomy data for a date range.

Plan: free and paid
Credits: 1 per request

Choose this when:

• You need multiple days of astronomy data in one request

• You want sunrise, sunset, day length, and moon phase across a range of dates

Returns an object with location and an astronomy array. 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.

Parse one user-agent string.

Plan: paid only
Credits: 1

Choose this when:

• You need structured browser, device, engine, and operating-system data for one user-agent string

• You need to classify crawlers, bots, or malformed user agents

This MCP tool parses the explicit uaString value you provide. It does not infer a caller user-agent from the MCP connection.

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

Parse multiple user-agent strings in one request.

Plan: paid only
Credits: 1 per user-agent string

Choose this when:

• You need structured parsing for more than one user-agent string

• You are processing log samples or traffic batches

This MCP tool parses only the explicit uaStrings values you provide.

The default cap is 1,000 items per MCP request. You can change it with IPGEOLOCATION_MCP_MAX_BULK_ITEMS.

Company and ASN holder lookup for one IP.

Plan: paid only
Credits: 1

Choose this when:

• You only need the company using an IP and the ASN holder

• You want a small response instead of full geolocation data

If the same prompt also needs security, abuse, city, timezone, or network details, prefer lookup_ip with targeted fields and include modules.

Returns company and asn objects.

Currency and country metadata for one IP.

Plan: free and paid
Credits: 1

Choose this when:

• You only need currency, country calling code, TLD, or languages for one IP

• You want a smaller response than full lookup_ip

Returns currency and country_metadata.

Route and network details for one IP.

Plan: paid only
Credits: 1

Choose this when:

• You only need route prefix, connection type, or anycast status

• You want a smaller response than full lookup_ip

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

Detailed ASN lookup.

Plan: paid only
Credits: 1

Choose this when:

• You need ASN metadata beyond the basic ASN object returned by lookup_ip

• You need peers, upstreams, downstreams, routes, or WHOIS data

Call this once with the include set you need, then filter locally from the response instead of making repeat calls to reshape the same data.

Abuse contact lookup for one IP.

Plan: paid only
Credits: 1

Choose this when:

• You only need abuse contact details for one IP

• You want the smallest and lowest-cost abuse-only path

If the same prompt also needs geolocation or security data, prefer lookup_ip with targeted fields and include=abuse or include=security,abuse.

Returns the abuse route, country, name, organization, address, emails, and phone numbers.

Credit Costs

Each upstream API request uses credits from your ipgeolocation.io account.

For current plan details, monthly credits, and pricing, please visit our pricing page.

Error Handling

All tools return structured errors instead of crashing the server.

Exact status codes can vary by endpoint and request mode. If an upstream endpoint returns another error, we pass that error back with a structured message.

Pricing

For current plan details, credits, and pricing, please visit our pricing page.

Building from Source

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

Run the built server directly:

IPGEOLOCATION_API_KEY=<IPGEOLOCATION_API_KEY> node dist/index.js

Inspect it with the MCP Inspector:

IPGEOLOCATION_API_KEY=<IPGEOLOCATION_API_KEY> npx @modelcontextprotocol/inspector node dist/index.js

Testing

Run the full test suite:

npm test

Run targeted suites:

npm run test:unit
npm run test:integration

How It Works

We run this package as a stdio MCP server on top of our v3 API portfolio.

What happens at runtime:

1. Your MCP client starts the server.

2. The client reads the tool list and tool descriptions.

3. The client calls the tool that best fits the prompt.

4. We validate inputs, call the upstream API, and return structured results.

5. For deterministic tools, we keep recent responses in the server process cache so repeated requests for the same input can return faster and avoid duplicate upstream calls.

Three tools, lookup_company, lookup_currency, and lookup_network, are convenience wrappers around the broader IP lookup response. We expose them separately because they are easier for clients to discover when the user only needs one narrow slice of data.

Caching and Refresh

We cache deterministic tool responses in process memory to reduce repeated upstream requests for the same input.

Why we do this:

• Faster responses for repeated lookups

• Lower credit usage when the same request is asked again

• Less duplicate traffic to upstream APIs

• Better behavior when a client retries or revisits the same question

Important points:

• This is server-side cache in the MCP process, not client model memory

• Default TTL is 300000 ms, which is 5 minutes

• Cache clears when the MCP server process stops or restarts

• A fresh upstream call happens when the TTL expires, the request shape changes, or force_refresh is set to true

Cached tools:

• 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

Live, uncached tools:

• get_my_ip

• get_timezone

• convert_timezone

• get_astronomy

Use force_refresh: true on cached tools when you explicitly want a fresh upstream response instead of a cached one.

Environment Variables

License

MIT License

Privacy Policy

See our Privacy Policy for details on how we handle data.

Links

• IPGeolocation Website

• GitHub Repository

• API Documentation

• Pricing

• Sign Up