We include a manifest.json following the MCPB spec (v0.3). Claude Desktop 0.10.0 and later can install it directly with no manual config. Claude Desktop prompts for your API key during setup.

To configure manually instead, add to claude_desktop_config.json:

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

Add to .cursor/mcp.json:

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

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

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

Add to your VS Code settings.json:

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

User prompt: "Where is 203.0.113.42 located, and is it using a VPN?"

What happens:

1. We call lookup_ip with ip=203.0.113.42 and include=security (3 credits on paid plan)
2. Returns geolocation (country, city, coordinates) plus security flags (is_vpn, vpn_provider_names, threat_score)
3. We return the location and whether the IP is behind a VPN

Cost optimization: If you only need the VPN check without geolocation, the client can call check_security instead (2 credits).

User prompt: "What time is it at JFK airport right now, and what would that be in Tokyo Narita?"

What happens:

1. We call convert_timezone with iata_from=JFK and iata_to=NRT
2. Returns the current time at JFK, the equivalent time at NRT, and the hour/minute difference
3. Also returns airport details (name, city, elevation) for both airports

Works on the free plan. 1 credit.

User prompt: "When will the sun rise in San Francisco each day this week?"

What happens:

1. We call get_astronomy_time_series with location=San Francisco, CA, dateStart=2026-03-04, and dateEnd=2026-03-10
2. Returns daily astronomy data including sunrise, sunset, moonrise, moonset, twilight, and moon phases for each day
3. We format the sunrise times into a readable list

Works on the free plan. 1 credit for the entire range (up to 90 days).

User prompt: "Who operates 1.1.1.1?"

What happens:

1. We call lookup_company with ip=1.1.1.1
2. Returns the company using the IP (APNIC Research and Development) and the ASN holder (Cloudflare, Inc.)
3. We explain the difference: Cloudflare routes the IP block, but APNIC holds the allocation

Paid plans only. 1 credit.

User prompt: "Check these IPs for threats: 1.2.3.4, 5.6.7.8, 9.10.11.12"

What happens:

1. We call bulk_security_check with all three IPs in a single request
2. Returns threat scores, VPN/proxy/Tor flags, bot detection, and provider names for each IP
3. We summarize which IPs are clean and which have security concerns

Paid plans only. 2 credits per IP (6 credits total).

Geolocation data for any IPv4/IPv6 address or domain. Uses GET /v3/ipgeo. Costs 1 credit.

Free plan returns: IP, location (continent, country, state, district, city, zipcode, coordinates, is_eu, country_flag, country_emoji, geoname_id), country_metadata (calling_code, tld, languages), currency (code, name, symbol), timezone (name, offset, DST info, current_time), basic ASN (as_number, organization, country).

Paid plans add: network (connection_type, route, is_anycast), company (name, type, domain), extended ASN (type, domain, date_allocated, rir). The ASN object is the organization holding the IP block allocation from a registry. The company object is the organization actually using that IP. They match when the ASN holder uses the IPs directly, and differ when IPs are subleased.

Cost optimization: Use include=security&fields=security to get only security data for 2 credits instead of 3. Use include=abuse&fields=abuse for abuse data at 1 credit instead of 2.

Geolocation data for up to 1,000 IPs per MCP request (configurable via env var). Uses POST /v3/ipgeo-bulk. Paid plans only.

Returns the public IP of the machine running this server. No parameters, no API key needed, no credits charged.

Check any IP against our threat intelligence database. Uses GET /v3/security. Paid plans only, 2 credits.

Returns: threat_score (0-100), is_tor, is_proxy, proxy_provider_names, proxy_confidence_score, proxy_last_seen, is_residential_proxy, is_vpn, vpn_provider_names, vpn_confidence_score, vpn_last_seen, is_relay, relay_provider_name, is_anonymous, is_known_attacker, is_bot, is_spam, is_cloud_provider, cloud_provider_name.

We return the same data as lookup_ip with include=security, but at 2 credits instead of 3 because we skip base geolocation.

Same as check_security but for up to 1,000 IPs per MCP request by default. Paid plans only, 2 credits per valid IP.

Timezone information for any location. Uses GET /v3/timezone. Works on all plans, 1 credit.

Look up by timezone name, coordinates, city, IP, airport code, or UN/LOCODE. All lookup modes work on free and paid plans.

Returns: Timezone name, UTC offset, current time in multiple formats, DST status, DST transition dates. Airport lookups also return airport name, city, elevation, and coordinates.

Convert a time from one location to another. Uses GET /v3/timezone/convert. Works on all plans, 1 credit.

Both source and destination can be timezone names, coordinates, cities, airport codes, or UN/LOCODEs.

Returns: Original time, converted time, diff_hour, and diff_min.

Astronomical data for any location on any date. Uses GET /v3/astronomy. Works on all plans, 1 credit.

Returns: Sunrise/sunset, moonrise/moonset, all twilight phases (civil, nautical, astronomical), golden hour, blue hour, solar noon, day length, sun and moon altitude/azimuth/distance, moon phase and illumination percentage.

Daily astronomical data for a date range in a single request. Uses GET /v3/astronomy/timeSeries. Works on all plans, 1 credit per request regardless of range length.

Does not include real-time positional data (sun/moon altitude, azimuth, distance). For that, use get_astronomy with a specific date.

Parse any user-agent string into structured device, browser, OS, and engine details. Uses POST /v3/user-agent. Paid plans only, 1 credit.

Returns: user_agent_string, name (browser/bot name), type (Browser, Crawler, etc.), version, version_major, device (name, type, brand, cpu), engine (name, type, version, version_major), operating_system (name, type, version, version_major, build).

Parse up to 1,000 user-agent strings per MCP request by default. Uses POST /v3/user-agent-bulk. Paid plans only, 1 credit per UA string.

Identify which organization is using a specific IP address. Uses GET /v3/ipgeo with fields filtered to company and ASN data. Paid plans only, 1 credit.

Returns two objects: the company using the IP and the ASN holder. They match when the ASN holder uses the IPs directly, and differ when IPs are subleased. For example, 1.1.1.1 has ASN "Cloudflare, Inc." (who routes it) but company "APNIC Research and Development" (who owns the block).

Returns: company (name, type, domain) and asn (as_number, organization, country, type, domain, date_allocated, rir).

Local currency and country metadata for any IP address. Uses GET /v3/ipgeo with fields filtered to currency and country_metadata. Works on all plans, 1 credit.

Returns: currency (code, name, symbol) and country_metadata (calling_code, tld, languages). For example, a Japanese IP returns currency code "JPY", name "Japanese Yen", symbol "¥", calling code "+81", TLD ".jp", and languages ["ja"].

Network routing information and anycast detection. Uses GET /v3/ipgeo with fields filtered to network data. Paid plans only, 1 credit.

Returns: network (connection_type, route, is_anycast). The route field shows the announced BGP prefix (e.g. "1.1.1.0/24"). The is_anycast field indicates whether the IP is served from multiple geographic locations via anycast routing.

Detailed ASN information. Uses GET /v3/asn. Paid plans only, 1 credit.

Basic ASN data (as_number, organization, country) is already included in every lookup_ip response on all plans. Our dedicated endpoint adds asn_name, allocation_status, route counts, and optional peers/downstreams/upstreams/routes/whois data.

Returns: AS number, asn_name, organization, country, type (ISP/Business/Hosting/etc), domain, RIR, allocation date, allocation status, IPv4 and IPv6 route counts. Optionally: peer/upstream/downstream ASNs, announced routes, raw WHOIS text.

Find who to contact about abuse from a given IP. Uses GET /v3/abuse. Paid plans only, 1 credit.

Abuse data is also available through lookup_ip with include=abuse (2 credits total). Our dedicated endpoint costs 1 credit when you only need abuse contact data without geolocation.

Returns: Organization name, abuse email addresses, phone numbers, mailing address, network route, country, and kind.