Skip to main content
Glama
IPGeolocation MCP Server

IPGeolocation MCP Server

Bulk IP Geolocation

bulk_lookup_ip
Read-only

Look up geolocation, ASN, security, and abuse data for up to 250 IPs or domains in one batch request; retrieve oversized results through cached pages.

Instructions

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ips": "<ips>"
    },
    "name": "bulk_lookup_ip"
  }
}

Input Schema

NameRequiredDescriptionDefault
ipsYesArray of IPv4 and/or IPv6 addresses to look up. Minimum 1, maximum 250 in this MCP server. Domain names are also accepted.
langNoResponse language code (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar). Defaults to en.
fieldsNoComma-separated dot-path fields to return per IP (e.g. location.city,asn.organization). Reduces response size and can reduce credit cost when combined with include. Fields under security or abuse auto-add that module. location.accuracy_radius/confidence/locality auto-add geo_accuracy; location.dma_code auto-adds dma_code. Optional modules require a paid plan.
includeNoComma-separated extra modules to include per IP. Options: security (+2 credits/IP), abuse (+1 credit/IP), hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or *. An unfiltered paid * response costs 4 credits/IP; fields/excludes can reduce returned modules and cost.
excludesNoComma-separated dot-path fields to exclude per IP (e.g. currency,time_zone).
force_refreshNoDefault false. When true, bypasses cached bulk geolocation data; a successful refresh makes a new upstream request and can consume credits.

Output Schema

NameRequiredDescriptionDefault
pageNo
errorNoPresent when the whole tool call fails, with isError: true.
itemsNoPresent on success: complete API results in input order, including any per-item error messages.
errorsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.0.4
    • changedInput schema / properties / include / description
      Previous value: -"Comma-separated extra modules to include per IP. Options: security (+2 credits/IP), abuse (+1 credit/IP), hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or * for all (4 credits/IP total)."New value: +"Comma-separated extra modules to include per IP. Options: security (+2 credits/IP), abuse (+1 credit/IP), hostname, liveHostname, hostnameFallbackLive, user_agent, geo_accuracy, dma_code, or *. An unfiltered paid * response costs 4 credits/IP; fields/excludes can reduce returned modules and cost."
    • changedInput schema / properties / lang / description
      Previous value: -"Response language code (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt). Defaults to en."New value: +"Response language code (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar). Defaults to en."
  2. Changed2 schema fields changedv2.0.3
    • removedOutput schema / properties / items / items / additionalProperties / anyOf
      Removed value: -[
      -  {
      -    "type": "null"
      -  },
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "array"
      -  },
      -  {
      -    "type": "object"
      -  }
      -]
    • addedOutput schema / properties / items / items / additionalProperties / type
      Added value: +[
      +  "null",
      +  "boolean",
      +  "number",
      +  "string",
      +  "array",
      +  "object"
      +]
  3. Changed5 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 per IP (e.g. location.city,asn.organization). Reduces response size and can reduce credit cost when combined with include. If fields reference include-only modules (for example security.* or abuse.*), this server auto-adds required include modules."New value: +"Comma-separated dot-path fields to return per IP (e.g. location.city,asn.organization). Reduces response size and can reduce credit cost when combined with include. Fields under security or abuse auto-add that module. location.accuracy_radius/confidence/locality auto-add geo_accuracy; location.dma_code auto-adds dma_code. Optional modules require a paid plan."
    • changedInput schema / properties / ips / description
      Previous value: -"Array of IPv4 and/or IPv6 addresses to look up. Minimum 1, maximum 1,000 in this MCP server. Domain names are also accepted."New value: +"Array of IPv4 and/or IPv6 addresses to look up. Minimum 1, maximum 250 in this MCP server. Domain names are also accepted."
    • changedInput schema / properties / ips / maxItems
      Previous value: -1000New value: +250
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "error": {
      +      "additionalProperties": false,
      +      "description": "Present when the whole tool call fails, 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"
      +    },
      +    "errors": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "category": {
      +            "const": "upstream_item",
      +            "type": "string"
      +          },
      +          "guidance": {
      +            "type": "string"
      +          },
      +          "input": {
      +            "type": "string"
      +          },
      +          "input_index": {
      +            "maximum": 9007199254740991,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "message": {
      +            "type": "string"
      +          },
      +          "retryable": {
      +            "type": "boolean"
      +          },
      +          "source": {
      +            "const": "ipgeolocation_api",
      +            "type": "string"
      +          },
      +          "status": {
      +            "description": "Present only when the API supplied an item HTTP status.",
      +            "maximum": 9007199254740991,
      +            "minimum": -9007199254740991,
      +            "type": "integer"
      +          }
      +        },
      +        "required": [
      +          "input_index",
      +          "input",
      +          "source",
      +          "category",
      +          "message",
      +          "retryable",
      +          "guidance"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "items": {
      +      "description": "Present on success: complete API results in input order, including any per-item error messages.",
      +      "items": {
      +        "additionalProperties": {
      +          "anyOf": [
      +            {
      +              "type": "null"
      +            },
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "array"
      +            },
      +            {
      +              "type": "object"
      +            }
      +          ]
      +        },
      +        "propertyNames": {
      +          "type": "string"
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "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"
      +}
  4. 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 bulk geolocation data; a successful refresh makes a new upstream request and can consume credits."New value: +"Default false. When true, bypasses cached bulk geolocation data; a successful refresh makes a new upstream request and can consume credits."
  5. 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 bulk geolocation data; a successful refresh makes a new upstream request and can consume credits."
  6. First observedv1.0.10

TDQS

A4.3/5.0
Behavior4/5

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

Annotations only declare readOnlyHint and openWorldHint, but the description goes well beyond them: per-module credit costs, unpaid-plan gating, non-billing for private/bogon/malformed IPs, force_refresh consuming credits, and a non-retryable resource_limit error where credits may already have been spent. That last warning is exactly the kind of hidden cost/residual-state behavior an agent needs before calling. It doesn't describe the response shape, but an output schema exists, so this is a minor gap.

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 opening and the caching/error paragraphs are front-loaded and information-dense, but the credit enumeration is sprawling (base 1, security +2, abuse +1, security-only 2, abuse-only 1, both without base 3) and partly restates costs already given in the include parameter's schema description. The 250-IP limit is also repeated from maxItems. Some sentences could be consolidated without loss.

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

Completeness5/5

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

For a paid, rate-limited bulk endpoint with an output schema and full annotation coverage, the description covers everything material: batching limits, credit economics, caching path, failure mode, and the sibling alternative. An agent has enough to decide to call it and to predict cost and error outcomes.

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 already 100%, so the baseline is 3; the description adds real value on top by noting that fields, excludes, lang, and include behave like lookup_ip per item and that this server infers include modules from fields. It also ties include/fields choices to credit cost, which the schema only partially covers.

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?

The description opens with a specific verb, resource, and scope: "Read-only bulk IP lookup via POST /v3/ipgeo-bulk." It states the batch nature and the endpoint, and explicitly differentiates from bulk_security_check ("dedicated security-only batch responses"), so an agent can distinguish it from siblings without opening a 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?

It gives clear operating context: 250-IP cap with larger batches rejected before any API call, cached pages served via get_cached_result without extra credits, and bulk_security_check as the alternative for security-only batches. It does not explicitly state when to prefer lookup_ip over this tool for small batches, which is the one missing routing rule.

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