Maxminddb MCP

The MaxMindDB MCP server is a powerful geolocation and network intelligence query tool that supports advanced filtering, state iteration, and automatic updates through the MaxMindDB database.

Location services Research and data #Geolocation #Network query #Data filtering #Automatic update .Go

rating : 2 points

downloads : 7.6K

update time : 2025-09-18

Open Site

What is MaxMindDB MCP Server?

This is a geolocation query server based on the Model Context Protocol (MCP) that can query the geolocation information, network attributes, and other related data of IP addresses. It supports multiple MaxMind database formats, including GeoIP2 and GeoLite2, and provides powerful filtering and query functions.

How to use MaxMindDB MCP Server?

Through simple configuration files and client integration, you can easily query IP address information, analyze network ranges, filter IP addresses that meet specific conditions, and automatically update the database to ensure data accuracy.

Application scenarios

It is suitable for scenarios such as network security analysis, geolocation services, user behavior analysis, content localization, fraud detection, and network traffic monitoring.

Main features

Multi - data source support

Supports three data source configuration methods: MaxMind account, directory scanning, and GeoIP.conf compatible mode.

Advanced filtering function

Provides more than 11 filtering operators and supports precise queries and conditional filtering by any field.

Stateful iterative query

Supports efficient queries for large - scale network ranges and has a recoverable iterator function.

Automatic update

Automatically downloads and updates database files from MaxMind to ensure the data is up - to - date.

File monitoring

Monitors changes in database files in real - time and dynamically loads new or updated database files.

Flexible configuration

Supports TOML configuration files and GeoIP.conf compatible configurations to meet different usage requirements.

Advantages

Supports multiple data sources and configuration methods, with strong flexibility

Provides powerful filtering and query functions to meet complex requirements

The automatic update mechanism ensures data timeliness

Good client compatibility, supporting multiple AI assistant platforms

The stateful iterator improves the efficiency of large - scale queries

Limitations

Requires a MaxMind account and license key to obtain complete data

The free GeoLite2 database has relatively low accuracy

Large - scale network queries may consume more memory resources

Requires regular maintenance of configurations and update settings

How to use

Install the server

Install the MaxMindDB MCP server through Go or compile and install it from the source code.

Create a configuration file

Create a config.toml configuration file in the ~/.config/maxminddb - mcp/ directory.

Configure the client

Configure the MCP server connection according to the AI assistant platform you are using.

Start querying

Call the IP query and network analysis functions through the client tool.

Usage examples

IP geolocation query

Query detailed geolocation information of a specific IP address, including country, city, latitude, and longitude.

Network range analysis

Analyze all IP addresses within a specific network range and filter out IPs that meet specific conditions.

Residential IP identification

Identify and filter out IP addresses of the residential network type for user behavior analysis.

Multi - condition filtering query

Use multiple filtering conditions for complex queries, such as IP addresses in a specific country that are not proxy servers.

Frequently Asked Questions

How to obtain a MaxMind license key?

What is the difference between the free and paid versions of the database?

What should I do if the server fails to start?

How to verify if the server is working properly?

Which client platforms are supported?

What is the frequency of automatic database updates?

Related resources

GitHub project repository

The project's source code and latest version

MaxMind official website

Official MaxMind service and database information

Model Context Protocol specification

The official specification and documentation of the MCP protocol

GeoIP.conf configuration guide

Detailed instructions for the MaxMind GeoIP configuration file

ISC license information

Detailed information about the ISC license used by the project

🚀 MaxMindDB MCP Server

MaxMindDB MCP Server is a powerful Model Context Protocol (MCP) server. It offers comprehensive geolocation and network intelligence through MaxMindDB databases. You can query GeoIP2, GeoLite2, and custom MMDB files with advanced filtering, stateful iteration, and automatic updates.

⚠️ Important Note

This is an unofficial project and is not endorsed by MaxMind Inc. This MCP server is an independent implementation. For official MaxMind products and support, please visit maxmind.com.

✨ Features

Multiple Data Sources: It supports MaxMind accounts, directory scanning, and GeoIP.conf compatibility.
Advanced Filtering: You can query by any MMDB field with 11+ operators (equals, regex, comparisons, etc.).
Stateful Iteration: It can process large network ranges efficiently with resumable iterators.
Auto-updating: The server can automatically download and update databases from MaxMind.
File Watching: It can dynamically load new or updated database files.
Flexible Configuration: It uses TOML config with GeoIP.conf fallback support.

🚀 Quick Start

📦 Installation

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

Basic Configuration

Create ~/.config/maxminddb-mcp/config.toml:

mode = "maxmind"
auto_update = true
update_interval = "24h"

[maxmind]
account_id = 123456
license_key = "your_license_key_here"
editions = ["GeoLite2-City", "GeoLite2-Country", "GeoLite2-ASN"]
database_dir = "~/.cache/maxminddb-mcp/databases"

💻 Usage Examples

Client Integration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "maxminddb": {
      "command": "maxminddb-mcp",
      "env": {
        "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
      }
    }
  }
}

Alternative with existing GeoIP.conf:

{
  "mcpServers": {
    "maxminddb": {
      "command": "maxminddb-mcp"
    }
  }
}

Claude Code CLI

Add the MCP server to Claude Code CLI:

claude mcp add maxminddb maxminddb-mcp

To use with a custom config:

MAXMINDDB_MCP_CONFIG=/path/to/config.toml claude chat

Claude Code (VS Code Extension)

Install the Claude Code extension and add to VS Code settings:

{
  "claude.mcpServers": {
    "maxminddb": {
      "command": "maxminddb-mcp",
      "env": {
        "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
      }
    }
  }
}

Continue

Install the Continue extension and add to your Continue configuration (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "maxminddb",
      "command": "maxminddb-mcp",
      "env": {
        "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
      }
    }
  ]
}

Zed

Add to Zed settings (~/.config/zed/settings.json):

{
  "assistant": {
    "mcp_servers": [
      {
        "name": "maxminddb",
        "command": "maxminddb-mcp",
        "env": {
          "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
        }
      }
    ]
  }
}

Cline

Install Cline and add to VS Code settings:

{
  "cline.mcpServers": {
    "maxminddb": {
      "command": "maxminddb-mcp",
      "env": {
        "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
      }
    }
  }
}

Gemini CLI

Add to your Gemini CLI configuration:

{
  "mcpServers": {
    "maxminddb": {
      "command": "maxminddb-mcp",
      "env": {
        "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
      }
    }
  }
}

See the Gemini CLI MCP guide for more details.

Codex

Add to your Codex configuration file:

[mcp_servers.maxminddb]
command = "maxminddb-mcp"
env = { MAXMINDDB_MCP_CONFIG = "/path/to/your/config.toml" }

Or without custom config:

[mcp_servers.maxminddb]
command = "maxminddb-mcp"

Sourcegraph Cody

Add to Cody settings:

{
  "cody.experimental.mcp": {
    "servers": {
      "maxminddb": {
        "command": "maxminddb-mcp",
        "env": {
          "MAXMINDDB_MCP_CONFIG": "/path/to/your/config.toml"
        }
      }
    }
  }
}

LLM (Simon Willison)

Install the LLM tool and configure MCP:

# Install LLM
pip install llm

# Configure MCP server
llm mcp install maxminddb-mcp --command maxminddb-mcp

# Use with environment variable
MAXMINDDB_MCP_CONFIG=/path/to/config.toml llm chat -m claude-3.5-sonnet

Python SDK

pip install mcp

from mcp import ClientSession, StdioServerParameters

async with ClientSession(
    StdioServerParameters(
        command="maxminddb-mcp",
        env={"MAXMINDDB_MCP_CONFIG": "/path/to/config.toml"}
    )
) as session:
    await session.initialize()
    tools = await session.list_tools()
    result = await session.call_tool("lookup_ip", {"ip": "8.8.8.8"})

TypeScript SDK

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "maxminddb-mcp",
  env: { MAXMINDDB_MCP_CONFIG: "/path/to/config.toml" },
});

const client = new Client(
  {
    name: "maxminddb-client",
    version: "1.0.0",
  },
  { capabilities: {} }
);

await client.connect(transport);
const result = await client.callTool({
  name: "lookup_ip",
  arguments: { ip: "8.8.8.8" },
});

Go SDK

go get github.com/mark3labs/mcp-go

import (
    "github.com/mark3labs/mcp-go/client"
    "github.com/mark3labs/mcp-go/transport/stdio"
)

cmd := exec.Command("maxminddb-mcp")
cmd.Env = append(cmd.Env, "MAXMINDDB_MCP_CONFIG=/path/to/config.toml")

transport := stdio.NewTransport(cmd)
mcpClient := client.New(transport)
// ... use client

Command Line Testing

Test the server directly using JSON-RPC:

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | maxminddb-mcp

# Test IP lookup
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"lookup_ip","arguments":{"ip":"8.8.8.8"}}}' | maxminddb-mcp

# Pretty output with jq
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | maxminddb-mcp | jq .

Configuration Notes

💡 Usage Tip

Path Requirements: Ensure maxminddb-mcp is in your system PATH or provide the full path to the binary.

Environment Variables: All clients support these environment variables:

MAXMINDDB_MCP_CONFIG: Path to configuration file

MAXMINDDB_MCP_LOG_LEVEL: Logging level (debug, info, warn, error)

MAXMINDDB_MCP_LOG_FORMAT: Log format (text, json)

Security: Store sensitive configuration (API keys) in files with appropriate permissions (600) rather than environment variables in client configs.

📚 Documentation

Configuration

Configuration Modes

The server supports three configuration modes (checked in order):

Environment variable: MAXMINDDB_MCP_CONFIG
User config: ~/.config/maxminddb-mcp/config.toml
GeoIP.conf compatibility: /etc/GeoIP.conf or ~/.config/maxminddb-mcp/GeoIP.conf

TOML Configuration

Complete configuration example

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

Configuration Options

Iterator Settings:

iterator_ttl (default: "10m"): How long idle iterators are kept before cleanup
iterator_cleanup_interval (default: "1m"): How often to check for expired iterators

GeoIP.conf Compatibility

Existing GeoIP.conf users

The server automatically detects and uses existing GeoIP.conf files:

# Example GeoIP.conf
AccountID 123456
LicenseKey your_license_key_here
EditionIDs GeoLite2-Country GeoLite2-City GeoLite2-ASN
DatabaseDirectory /var/lib/GeoIP

No additional configuration needed - the server will automatically use compatibility mode.

Available Tools

Core Tools

`lookup_ip`

Look up geolocation and network information for a specific IP address.

Parameters:

ip (required): IP address to lookup (IPv4 or IPv6)
database (optional): Specific database filename to query

Example:

{
  "name": "lookup_ip",
  "arguments": {
    "ip": "8.8.8.8",
    "database": "GeoLite2-City.mmdb"
  }
}

Response:

{
  "ip": "8.8.8.8",
  "network": "8.8.8.0/24",
  "data": {
    "country": {
      "iso_code": "US",
      "names": { "en": "United States" }
    },
    "location": {
      "latitude": 37.4056,
      "longitude": -122.0775
    }
  }
}

`lookup_network`

Query all IP addresses in a network range with powerful filtering capabilities.

Parameters:

network (required): CIDR network to scan (e.g., "192.168.1.0/24")
database (optional): Specific database to query
filters (optional): Array of filter objects. Each object must include field, operator, and value.
filter_mode (optional): "and" (default) or "or"
max_results (optional): Maximum results to return (default: 1000)
iterator_id (optional): Resume existing iterator
resume_token (optional): Fallback token for expired iterators

Filtering Examples

Filter by country:

{
  "name": "lookup_network",
  "arguments": {
    "network": "10.0.0.0/8",
    "filters": [
      {
        "field": "country.iso_code",
        "operator": "in",
        "value": ["US", "CA", "MX"]
      }
    ]
  }
}

Filter residential IPs:

{
  "name": "lookup_network",
  "arguments": {
    "network": "192.168.0.0/16",
    "filters": [
      {
        "field": "traits.user_type",
        "operator": "equals",
        "value": "residential"
      }
    ]
  }
}

Common mistakes and validation:

Do not pass filters as strings like "traits.user_type=residential". The server rejects this with invalid_filter and a hint to use objects: { "field": "traits.user_type", "operator": "equals", "value": "residential" }.
filters must be an array of objects; other types are invalid.
operator must be supported (see list below). Short aliases (eq, ne, gt, gte, lt, lte) are also accepted.

Complex filtering (non-proxy IPs):

{
  "name": "lookup_network",
  "arguments": {
    "network": "10.0.0.0/24",
    "filters": [
      {
        "field": "traits.is_anonymous_proxy",
        "operator": "equals",
        "value": false
      },
      {
        "field": "traits.is_satellite_provider",
        "operator": "equals",
        "value": false
      }
    ],
    "filter_mode": "and"
  }
}

`list_databases`

List all available MaxMind databases with metadata.

Example:

{
  "name": "list_databases",
  "arguments": {}
}

Response:

{
  "databases": [
    {
      "name": "GeoLite2-City.mmdb",
      "type": "City",
      "description": "GeoLite2 City Database",
      "last_updated": "2024-01-15T10:30:00Z",
      "size": 67108864
    }
  ]
}

`update_databases`

Manually trigger database updates (MaxMind/GeoIP modes only).

Example:

{
  "name": "update_databases",
  "arguments": {}
}

Filter Operators

Supported Operators:

equals: Exact match
not_equals: Not equal to value
in: Value is in provided array
not_in: Value is not in provided array
contains: String contains substring
regex: Matches regular expression
greater_than: Numeric comparison
greater_than_or_equal: Numeric comparison (≥)
less_than: Numeric comparison
less_than_or_equal: Numeric comparison (≤)
exists: Field exists (boolean value)

Operator Aliases: For convenience, short operator aliases are supported (case-insensitive):

eq → equals
ne → not_equals
gt → greater_than
gte → greater_than_or_equal
lt → less_than
lte → less_than_or_equal

Error Handling

All tools return structured error responses with machine-readable error codes:

{
  "error": {
    "code": "db_not_found",
    "message": "Database not found: invalid_db.mmdb"
  }
}

Common Error Codes:

db_not_found: Specified database does not exist
invalid_ip: IP address format is invalid
invalid_network: Network CIDR format is invalid
invalid_filter: Filter validation failed
iterator_not_found: Iterator ID not found or expired
parse_error: Failed to parse request parameters

Advanced Features

Stateful Iterator System

For large network queries, the server uses a stateful iterator system:

Fast Path: Resume active iterations using iterator_id
Resilient Path: Resume from resume_token after expiration
Automatic Cleanup: Expired iterators cleaned up after TTL
Efficient Skip: Skip to resume point without re-processing

Example iteration workflow:

// First call - creates iterator
{
  "name": "lookup_network",
  "arguments": {
    "network": "10.0.0.0/8",
    "max_results": 1000
  }
}

// Response includes iterator_id for continuation
{
  "results": [...],
  "iterator_id": "iter_abc123",
  "resume_token": "eyJ0eXAiOiJKV1Q...",
  "has_more": true
}

// Continue with iterator_id (fast path)
{
  "name": "lookup_network",
  "arguments": {
    "network": "10.0.0.0/8",
    "iterator_id": "iter_abc123",
    "max_results": 1000
  }
}

Auto-updating

Automatic database updates

Configure automatic updates in your TOML config:

auto_update = true
update_interval = "24h"  # Check every 24 hours

The server will:

Check for database updates on the specified interval
Download only if MD5 checksums have changed
Gracefully reload databases without interrupting active queries
Log update status and any errors

Manual Updates: Use the update_databases tool to trigger immediate updates.

File Watching

Directory mode with file watching

In directory mode, the server watches for filesystem changes:

mode = "directory"

[directory]
paths = ["/path/to/mmdb/files"]

Supported events:

Create: Automatically loads new MMDB files
Write: Reloads modified databases
Remove: Removes databases from available list
Rename: Handles file renames gracefully

Subdirectory support: Recursively watches all subdirectories for MMDB files.

Troubleshooting

Common Issues

Server not starting

Check configuration:

# Verify config file syntax
maxminddb-mcp --help

# Test configuration loading
MAXMINDDB_MCP_LOG_LEVEL=debug maxminddb-mcp

Common causes:

Invalid TOML syntax in config file
Missing MaxMind credentials
Insufficient file permissions
Invalid database directory path

Database loading failures

Check database status:

# Enable debug logging
MAXMINDDB_MCP_LOG_LEVEL=debug maxminddb-mcp

Common causes:

Corrupt MMDB files (check file integrity)
Insufficient disk space for downloads
Network connectivity issues to updates.maxmind.com
Expired MaxMind subscription

Claude Desktop integration

Verify server path:

# Check server is in PATH
which maxminddb-mcp

# Test server directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | maxminddb-mcp

Configuration file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Debug Mode

Enable detailed logging for troubleshooting:

# Environment variables
MAXMINDDB_MCP_LOG_LEVEL=debug
MAXMINDDB_MCP_LOG_FORMAT=json

# Or in config.toml
log_level = "debug"
log_format = "json"

Configuration Validation

The server validates all configuration on startup and provides detailed error messages:

Required fields for each mode
Valid duration formats (e.g., "24h", "10m")
Path expansion and validation
Network connectivity checks

Performance Considerations

Memory Usage

Base memory: ~50MB
Database storage: 100 - 500MB depending on editions

Optimization Tips

💡 Usage Tip

Avoid unnecessary iterations: use selective filters and appropriate max_results.

Database selection: Only download needed editions to reduce memory usage.

Update frequency: Balance freshness vs. network usage with update_interval.

Filter efficiency: Use selective filters early to reduce processing.