MaxMindDB MCP Server

Overview Schema Source Related Servers Discussions Admin

Query an address range

lookup_range

Read-only

Find stored network records overlapping an inclusive IP start/end range, with optional filters and field selection. Use it for range-based queries when CIDR bounds do not apply.

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

TableJSON Schema

Name	Required	Description
`end_ip`	Yes	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.
`fields`	No	Optional 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.
`filters`	No	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.
`database`	No	Exact filename from list_databases. Required when more than one database is loaded. Repeat the same name on each page.
`start_ip`	Yes	First IPv4 or IPv6 address to include, for example 192.0.2.10. Zone identifiers are not supported.
`filter_mode`	No	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.
`iterator_id`	No	ID from the previous page. Omit on the first request. Send with the latest resume_token to continue if the iterator expires.
`max_results`	No	Maximum matching records to return on this page. Use a smaller page to reduce response size.
`resume_token`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	Yes
`has_more`	Yes
`iterator_id`	Yes
`resume_token`	Yes
`total_matched`	Yes
`total_processed`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.3.1Oct 18, 2026

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

First observedv0.1.0Oct 18, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, non-idempotent), so the description's real contribution is non-obvious semantics: results are deduplicated ('each overlapping network once') and may include networks extending beyond the bounds. It also discloses the pagination termination condition. It stops short of stating rate limits or what happens on iterator expiry, keeping it at a 4.

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

Conciseness5/5

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

Four dense sentences, each carrying distinct information: purpose, sibling routing, result semantics, and pagination protocol. No filler and the core purpose is front-loaded.

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 read tool with a full output schema, the description covers the remaining agent-facing gaps: dedup behavior, out-of-bounds inclusion, sibling routing, and page continuation. Return-value shape is already handled by the output schema, so nothing essential is missing.

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 description coverage is 100%, so the baseline is 3; the description earns an extra point by adding cross-page parameter behavior not obvious from the schema ('Repeat the endpoints and database on each page'), which tells the agent how start_ip/end_ip/database must be re-sent during iteration.

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 (Find) and resource (stored network records) scoped to an inclusive start/end IP range, and explicitly distinguishes itself from lookup_network by naming the CIDR-bound case as the sibling's territory. An agent can route between lookup_range and lookup_network 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?

Gives an explicit alternative with its selecting condition ('Use lookup_network when the bounds are a CIDR') and adds pagination guidance ('Repeat the endpoints and database on each page. Stop when has_more is false'), covering both when to pick this tool and how to drive it.

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

Deploy Server