MaxMindDB

You can run and query the MaxMindDB MCP Server to access geolocation and network data from MMDB databases. It supports automatic updates, file watching, and flexible configuration, letting you query GeoLite2, GeoIP2, and custom MMDB files with powerful filters and stateful iterators for large networks.

How to use

Install and run the server, then connect with an MCP client to perform lookups, filter large networks, and manage databases. You can query a single IP to retrieve country, city, location, and ASN data, or you can scan a large CIDR range with advanced filters and iterator support. Use auto-update to keep databases fresh and enable file watching if you work with a directory of MMDB files.

Typical usage patterns include starting the server with your chosen mode (for example, maxmind for direct MMDB lookups or directory to watch a folder of databases) and then querying via an MCP client. When you need to process many addresses efficiently, use the stateful iterator system to resume work from where you left off, avoiding re-processing data.

How to install

Prerequisites: you need a Go toolchain installed on your system to build or install the server.

# Option 1: Install from Go
go install github.com/oschwald/maxminddb-mcp/cmd/maxminddb-mcp@latest

# Option 2: Build from source
git clone https://github.com/oschwald/maxminddb-mcp.git
cd maxminddb-mcp
go build -o maxminddb-mcp cmd/maxminddb-mcp/main.go

Configuration and running

Configure the server using TOML, with support for three modes: maxmind, directory, and geoip_compat. The config enables auto updates, directory watching, and GeoIP.conf compatibility.

# Operation mode: "maxmind", "directory", or "geoip_compat"
mode = "maxmind"

# Auto-update settings
auto_update = true
update_interval = "24h"

# Iterator settings
iterator_ttl = "10m"
iterator_cleanup_interval = "1m"

# Logging (optional)
log_level = "info"  # debug, info, warn, error
log_format = "text" # text, json

[maxmind]
# MaxMind account credentials
account_id = 123456
license_key = "your_license_key_here"

# Databases to download
editions = [
  "GeoLite2-City",
  "GeoLite2-Country",
  "GeoLite2-ASN",
  "GeoIP2-City",
  "GeoIP2-Country"
]

# Storage location
database_dir = "~/.cache/maxminddb-mcp/databases"

# Custom endpoint (optional)
# endpoint = "https://updates.maxmind.com"

[directory]
# For directory mode - scan these paths for MMDB files
paths = [
  "/path/to/mmdb/files",
  "/another/path"
]

[geoip_compat]
# For GeoIP.conf compatibility mode
config_path = "/etc/GeoIP.conf"
database_dir = "/var/lib/GeoIP"

Security and best practices

Store sensitive configuration values, such as API keys, in files with restricted permissions (for example 600) rather than in environment variables within client configurations.

Troubleshooting

If the server does not start, verify your TOML syntax, credentials, and file permissions. Enable debug logging to gather more information and check for missing or invalid database paths.

Notes on updates and file watching

Automatic updates download only when checksums change and reload databases without interrupting active queries. In directory mode, the server watches for created, modified, removed, and renamed MMDB files, recursively including subdirectories.

Performance considerations

Expect modest memory usage for a small set of databases (roughly tens of megabytes to a few hundred megabytes per database). Optimize by selecting only needed editions, setting suitable iterator TTLs, and balancing update frequency with network usage.

Common commands at a glance

To run the server in stdio mode, use a local binary that reads its configuration from an environment variable. The configuration example shows how to pass the path to the TOML config.

Available tools

lookup_ip

Query a single IP address to retrieve geolocation and network data from the available MMDB databases.

lookup_network

Query a CIDR network range with optional filters and iterator support to retrieve matching results.

list_databases

List all available MMDB databases with metadata such as last updated and size.

update_databases

Manually trigger updates of databases when using MaxMind/GeoIP modes.