MaxMindDB MCP Server

Overview Schema Source Related Servers Discussions Admin

Query a network

lookup_network

Read-only

Find stored MaxMind network records overlapping a CIDR, with optional filters and field selection. Use to filter IP ranges and page through matching records.

Instructions

Find stored network records overlapping a CIDR, with optional filters and field selection. Returned networks may extend beyond the requested CIDR. Use lookup_range for start/end bounds or summarize_network for grouped counts. Repeat the network and database on each page. Stop when has_more is false.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`network`	Yes	IPv4 or IPv6 CIDR to scan, for example 192.168.1.0/24 or 2001:db8::/32. Broad queries may scan many records.
`database`	No	Exact filename from list_databases. Required when more than one database is loaded. Repeat the same name on each page.
`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.

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

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 / network / description

Previous value: -"CIDR network to scan (e.g., '192.168.1.0/24')"New value: +"IPv4 or IPv6 CIDR to scan, for example 192.168.1.0/24 or 2001:db8::/32. Broad queries may scan many records."

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

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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description adds genuinely non-obvious behavior beyond that: results may extend past the requested CIDR, pagination state must be carried forward by repeating network/database, and termination is signalled by has_more.

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 sentences, each load-bearing: purpose, an important behavioral caveat, sibling routing, then pagination contract. It is front-loaded with the identity of the tool and contains no filler.

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?

The tool has 8 parameters and an output schema, so return-shape explanation is unnecessary. The description still covers the pagination lifecycle and the overlap semantics that an agent must know to call and iterate correctly, and annotations carry the safety profile.

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 above baseline by adding cross-parameter semantics the schema does not: iterator/network/database must be repeated across pages, and pagination terminates on has_more rather than a result count.

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 opening sentence gives a precise verb and resource ('Find stored network records overlapping a CIDR') and immediately scopes the tool: overlap semantics rather than containment. It also names the two nearest siblings, lookup_range and summarize_network, so an agent can distinguish it without opening schemas.

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?

Explicit routing is provided: 'Use lookup_range for start/end bounds or summarize_network for grouped counts.' Pagination guidance is also given ('Repeat the network and database on each page. Stop when has_more is false.'), covering both the selection decision and the invocation loop.

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

Deploy Server