Skip to main content
Glama
IPGeolocation

IPGeolocation MCP Server

by IPGeolocation
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

IP Geolocation Lookup

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

Instructions

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 named by fields or an explicit include cannot be excluded as a whole. include=* follows fields/excludes without this explicit-token protection. 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.

Input Schema

NameRequiredDescriptionDefault
ipNoIPv4 address, IPv6 address, or domain name to look up. Domain lookups require a paid plan. Omit to use the server's public egress IP.
langNoResponse language code (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt). Paid plans only. Free plan returns a 401 error if you pass any value other than en. Defaults to en.
fieldsNoComma-separated dot-path fields to return (e.g. location.city,asn.organization). Works on all plans including free. Reduces response size and can reduce credit cost when combined with include. Fields under security or abuse auto-add that include module. location.accuracy_radius/confidence/locality auto-add geo_accuracy; location.dma_code auto-adds dma_code. Those optional modules require a paid plan.
includeNoComma-separated extra modules to include in the response. Paid plans only. Options: security (+2 credits), abuse (+1 credit), hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or * for all (4 credits total). Free plan cannot use this parameter.
excludesNoComma-separated dot-path fields to exclude from response (e.g. currency,location.continent_code). Works on all plans including free.
force_refreshNoDefault false. When true, bypasses cached lookup_ip data; a successful refresh makes a new upstream request and can consume credits.

Output Schema

NameRequiredDescriptionDefault
dataNoPresent on success: API result after field selection, redaction, and transport limits.
pageNo
errorNoPresent on failure, with isError: true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.0.3
    • removedOutput schema / properties / data / additionalProperties / anyOf
      Removed value: -[
-  {
-    "type": "null"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "array"
-  },
-  {
-    "type": "object"
-  }
-]
    • addedOutput schema / properties / data / additionalProperties / type
      Added value: +[
+  "null",
+  "boolean",
+  "number",
+  "string",
+  "array",
+  "object"
+]
  2. Changed4 schema fields changedv2.0.1
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / fields / description
      Previous value: -"Comma-separated dot-path fields to return (e.g. location.city,asn.organization). Works on all plans including free. Reduces response size and can reduce credit cost when combined with include. If a field references an include-only module (for example security.* or abuse.*), this server auto-adds the required include module."New value: +"Comma-separated dot-path fields to return (e.g. location.city,asn.organization). Works on all plans including free. Reduces response size and can reduce credit cost when combined with include. Fields under security or abuse auto-add that include module. location.accuracy_radius/confidence/locality auto-add geo_accuracy; location.dma_code auto-adds dma_code. Those optional modules require a paid plan."
    • changedInput schema / properties / ip / description
      Previous value: -"IPv4 address, IPv6 address, or domain name to look up. Domain lookups require a paid plan. Omit to use the caller's IP."New value: +"IPv4 address, IPv6 address, or domain name to look up. Domain lookups require a paid plan. Omit to use the server's public egress IP."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "null"
+          },
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "string"
+          },
+          {
+            "type": "array"
+          },
+          {
+            "type": "object"
+          }
+        ]
+      },
+      "description": "Present on success: API result after field selection, redaction, and transport limits.",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "error": {
+      "additionalProperties": false,
+      "description": "Present on failure, with isError: true.",
+      "properties": {
+        "assistant_guidance": {
+          "type": "string"
+        },
+        "category": {
+          "type": "string"
+        },
+        "documented_status": {
+          "type": "boolean"
+        },
+        "explanation_hint": {
+          "type": "string"
+        },
+        "guidance": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "retryable": {
+          "type": "boolean"
+        },
+        "source": {
+          "enum": [
+            "mcp_server",
+            "ipgeolocation_api"
+          ],
+          "type": "string"
+        },
+        "status": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "source",
+        "category",
+        "message",
+        "retryable",
+        "guidance",
+        "assistant_guidance"
+      ],
+      "type": "object"
+    },
+    "page": {
+      "additionalProperties": false,
+      "properties": {
+        "cursor": {
+          "description": "Opaque cursor returned in page.cursor or page.next_cursor. Retrieval requires the same server process and API key and does not repeat the original lookup.",
+          "maxLength": 80,
+          "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}:\\d{1,16}$",
+          "type": "string"
+        },
+        "expires_at": {
+          "description": "ISO timestamp for idle expiry. Successful page reads extend the cache TTL; eviction or process restart can also remove the result.",
+          "type": "string"
+        },
+        "format": {
+          "const": "structuredContent_json",
+          "type": "string"
+        },
+        "json_fragment": {
+          "description": "JSON fragment of the original structuredContent. Fragments concatenate in offset order into the complete JSON, including bulk items and errors.",
+          "type": "string"
+        },
+        "next_cursor": {
+          "description": "Cursor for the next get_cached_result page, absent on the last page. Page reads never call the API or consume credits.",
+          "maxLength": 80,
+          "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}:\\d{1,16}$",
+          "type": "string"
+        },
+        "offset": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "source_tool": {
+          "type": "string"
+        },
+        "total_chars": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "source_tool",
+        "format",
+        "json_fragment",
+        "offset",
+        "total_chars",
+        "cursor",
+        "expires_at"
+      ],
+      "type": "object"
+    }
+  },
+  "type": "object"
+}
  3. Changed2 schema fields changedv2.0.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedInput schema / properties / force_refresh / description
      Previous value: -"Default false. Set true only when the user asks to bypass cached lookup_ip data; a successful refresh makes a new upstream request and can consume credits."New value: +"Default false. When true, bypasses cached lookup_ip data; a successful refresh makes a new upstream request and can consume credits."
  4. Changed1 schema field changedv1.0.15
    • changedInput schema / properties / force_refresh / description
      Previous value: -"Default false. Leave unset unless the user asks to refresh or rerun."New value: +"Default false. Set true only when the user asks to bypass cached lookup_ip data; a successful refresh makes a new upstream request and can consume credits."
  5. First observedv1.0.10

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/openWorld, but the description adds a lot beyond them: a granular credit cost model per module, free-plan vs paid-plan capability split (free plan rejects include and non-English lang with 401), cache-bypass semantics for force_refresh consuming credits, and the caveat that IP location is an estimate rather than a device position. These are exactly the behaviors an agent needs before invoking a metered lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core is front-loaded and the cost model comes early, which is right. But the description repeats the module list twice ('location, company/ASN, network, timezone, currency, security, abuse, user_agent, hostname, geo_accuracy, dma_code' then 'location, country_metadata, currency, asn, network, company, time_zone, security, abuse, user_agent, or hostname'), and the credit arithmetic is written out in repeated, laborious sentences that restate what the include schema already documents.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a metered, plan-gated, field-selective lookup, the description covers cost, plan tiers, field/exclude interaction, caching, and the accuracy caveat, so an agent can call it correctly. An output schema exists, yet the description still spends several sentences enumerating returned objects, which is redundant rather than missing — the completeness gap is small.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description contributes real semantics beyond the schema: explicit include tokens keep their modules even when fields omits them, include=* loses that protection, a root named by fields or an explicit include cannot be wholly excluded, and the server auto-adds include modules referenced by fields. Minor drawback is that this is buried in one dense paragraph rather than tied to parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read-only unified IP lookup via GET /v3/ipgeo') and frames the tool as the aggregate entry point covering location, company/ASN, network, security, abuse, etc. It explicitly names the sibling tools (lookup_asn, check_security, get_abuse_contact) that serve narrower purposes, so an agent can distinguish it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The closing sentence routes the agent to alternatives: 'lookup_asn provides ASN relationships, routes, and WHOIS; check_security and get_abuse_contact provide dedicated security and abuse responses.' Combined with the free-vs-paid plan restrictions, a caller knows the main conditions. It never states an explicit exclusion such as 'do not use this if you only need ASN data', so it falls short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools