Skip to main content
Glama
Sign In
MaxMindDB MCP Server

MaxMindDB MCP Server

by oschwald
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

Query an address range

lookup_range
Read-only

Find stored network records overlapping an inclusive start/end IP range, with optional filters and field selection. Use lookup_network when the bounds are a CIDR.

Instructions

Find stored network records overlapping an inclusive start/end IP range, with optional filters and field selection. Use lookup_network when the bounds are a CIDR. Returns each overlapping network once, including networks extending beyond the bounds. Repeat the endpoints and database on each page. Stop when has_more is false.

Input Schema

NameRequiredDescriptionDefault
end_ipYesLast address to include, for example 192.0.2.200. Must be at or after start_ip in the same address family, without a zone identifier.
fieldsNoOptional field paths. Returns an object keyed by each selected path. Use dots for map keys, numeric array indexes, or $ for the whole record. Omit or use [] for full records. Repeat on each page.
filtersNoConditions on record fields. For example, [{"field":"autonomous_system_number","operator":"equals","value":13335}]. Omit for no filtering on a new query. On paginated queries, omit to retain the original filters.
databaseNoExact filename from list_databases. Required when more than one database is loaded. Repeat the same name on each page.
start_ipYesFirst IPv4 or IPv6 address to include, for example 192.0.2.10. Zone identifiers are not supported.
filter_modeNoCombine filters with and (all must match) or or (any can match). Defaults to and for a new query. Omit when paging to retain the original mode.
iterator_idNoID from the previous page. Omit on the first request. Send with the latest resume_token to continue if the iterator expires.
max_resultsNoMaximum matching records to return on this page. Use a smaller page to reduce response size.
resume_tokenNoToken from the previous page, used if iterator_id is missing or expired. Omit on the first request. If the database build changed, start a new query.

Output Schema

NameRequiredDescriptionDefault
resultsYes
has_moreYesTrue when another matching record exists. Continue with the same query parameters.
iterator_idYesIdentifier for continuing this live query with the same parameters.
resume_tokenYesToken for resuming after the last returned record if the live iterator expires.
total_matchedYesCumulative matching records returned across pages, not the count on this page.
total_processedYesCumulative records processed across pages, including nonmatching records scanned ahead to find the next match.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.4.0
    • addedOutput schema / properties / has_more / description
      Added value: +"True when another matching record exists. Continue with the same query parameters."
    • addedOutput schema / properties / iterator_id / description
      Added value: +"Identifier for continuing this live query with the same parameters."
    • addedOutput schema / properties / resume_token / description
      Added value: +"Token for resuming after the last returned record if the live iterator expires."
    • addedOutput schema / properties / total_matched / description
      Added value: +"Cumulative matching records returned across pages, not the count on this page."
    • addedOutput schema / properties / total_processed / description
      Added value: +"Cumulative records processed across pages, including nonmatching records scanned ahead to find the next match."
  2. Changed11 schema fields changedv0.3.1
    • changedInput schema / properties / database / description
      Previous value: -"Database name from list_databases; required when more than one is loaded"New value: +"Exact filename from list_databases. Required when more than one database is loaded. Repeat the same name on each page."
    • addedInput schema / properties / end_ip / description
      Added value: +"Last address to include, for example 192.0.2.200. Must be at or after start_ip in the same address family, without a zone identifier."
    • changedInput schema / properties / filter_mode / description
      Previous value: -"How to combine filters: 'and' or 'or' (default: 'and')"New value: +"Combine filters with and (all must match) or or (any can match). Defaults to and for a new query. Omit when paging to retain the original mode."
    • changedInput schema / properties / filters / description
      Previous value: -"Filters for a new query; omit to keep filters when continuing a query"New value: +"Conditions on record fields. For example, [{\"field\":\"autonomous_system_number\",\"operator\":\"equals\",\"value\":13335}]. Omit for no filtering on a new query. On paginated queries, omit to retain the original filters."
    • addedInput schema / properties / filters / items / properties / field / description
      Added value: +"Field path from inspect_database, such as country.iso_code. Use dots for nested keys or numeric array indexes, or $ for the whole record."
    • addedInput schema / properties / filters / items / properties / operator / description
      Added value: +"Comparison to apply. eq, ne, gt, lt, gte, and lte are aliases for the corresponding equality and ordering operators."
    • addedInput schema / properties / filters / items / properties / value / description
      Added value: +"Comparison value. Use an array for in/not_in, a Go regular expression string for regex, or a substring for contains. For exists, true tests for a non-null field and false tests for a missing or null field. Ordering comparisons use numbers."
    • changedInput schema / properties / iterator_id / description
      Previous value: -"Resume existing iterator (fast path)"New value: +"ID from the previous page. Omit on the first request. Send with the latest resume_token to continue if the iterator expires."
    • changedInput schema / properties / max_results / description
      Previous value: -"Page size from 1 to 1000"New value: +"Maximum matching records to return on this page. Use a smaller page to reduce response size."
    • changedInput schema / properties / resume_token / description
      Previous value: -"Fallback token if iterator expired"New value: +"Token from the previous page, used if iterator_id is missing or expired. Omit on the first request. If the database build changed, start a new query."
    • addedInput schema / properties / start_ip / description
      Added value: +"First IPv4 or IPv6 address to include, for example 192.0.2.10. Zone identifiers are not supported."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only, non-destructive, non-idempotent behavior, and the description adds genuinely new semantics: deduplication ('Returns each overlapping network once') and the non-obvious inclusion of networks extending beyond the bounds. It further discloses pagination state handling and that a changed database build invalidates the iterator — context an agent could not get from the annotations.

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

Conciseness4/5

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

Four short sentences, front-loaded with purpose and routing before pagination mechanics. Minor redundancy with per-parameter schema text ('Repeat the endpoints and database on each page'), but no sentence is wasted.

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 9-parameter paginated query tool with a full output schema, the description covers selection, the sibling alternative, overlap semantics, and the full pagination lifecycle. Return-value detail can be left to the output schema, and the one response field that matters for control flow (has_more) is named.

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

Parameters3/5

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

Schema coverage is 100%, so start_ip, end_ip, fields, filters, database, max_results, iterator_id and resume_token are all documented in the schema. The description largely restates pagination rules already present per-parameter ('Repeat on each page'), adding only the has_more stop signal. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Find stored network records overlapping an inclusive start/end IP range') and immediately scopes it with 'optional filters and field selection'. It also names the sibling it is not — lookup_network, for CIDR bounds — so an agent can route without opening either schema.

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

Usage Guidelines5/5

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

Explicitly gives the alternative and the condition that selects it: 'Use lookup_network when the bounds are a CIDR.' It also supplies the terminating condition ('Stop when has_more is false') and the pagination rule ('Repeat the endpoints and database on each page'), leaving little to inference.

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