{"id":31405392,"url":"https://github.com/oschwald/maxminddb-mcp","last_synced_at":"2026-05-15T01:40:47.162Z","repository":{"id":313688993,"uuid":"1052292455","full_name":"oschwald/maxminddb-mcp","owner":"oschwald","description":"A powerful Model Context Protocol (MCP) server that provides comprehensive geolocation and network intelligence through MaxMindDB files","archived":false,"fork":false,"pushed_at":"2025-09-07T21:19:13.000Z","size":91,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T21:29:42.679Z","etag":null,"topics":["geoip","geoip2","maxmind","maxminddb","mcp","mmdb"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oschwald.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T19:44:34.000Z","updated_at":"2025-09-07T21:18:27.000Z","dependencies_parsed_at":"2025-09-07T21:29:48.039Z","dependency_job_id":"a9a411e4-c5eb-4cb8-9c0e-3ca0df99d3ca","html_url":"https://github.com/oschwald/maxminddb-mcp","commit_stats":null,"previous_names":["oschwald/maxminddb-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/oschwald/maxminddb-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oschwald","download_url":"https://codeload.github.com/oschwald/maxminddb-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oschwald%2Fmaxminddb-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277551126,"owners_count":25837605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geoip","geoip2","maxmind","maxminddb","mcp","mmdb"],"created_at":"2025-09-29T17:04:43.163Z","updated_at":"2025-09-29T17:04:44.426Z","avatar_url":"https://github.com/oschwald.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaxMindDB MCP Server\n\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n\nA powerful Model Context Protocol (MCP) server that provides comprehensive geolocation and network intelligence through MaxMindDB databases. Query GeoIP2, GeoLite2, and custom MMDB files with advanced filtering, stateful iteration, and automatic updates.\n\n\u003e **Important Notice**: 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](https://www.maxmind.com/).\n\n## Features\n\n- **Multiple Data Sources**: MaxMind accounts, directory scanning, and GeoIP.conf compatibility\n- **Advanced Filtering**: Query by any MMDB field with 11+ operators (equals, regex, comparisons, etc.)\n- **Stateful Iteration**: Process large network ranges efficiently with resumable iterators\n- **Auto-updating**: Automatic database downloads and updates from MaxMind\n- **File Watching**: Dynamic loading of new/updated database files\n- **Flexible Configuration**: TOML config with GeoIP.conf fallback support\n\n## Quick Start\n\n### Installation\n\n#### Option 1: Install from Go\n\n```bash\ngo install github.com/oschwald/maxminddb-mcp/cmd/maxminddb-mcp@latest\n```\n\n#### Option 2: Build from Source\n\n```bash\ngit clone https://github.com/oschwald/maxminddb-mcp.git\ncd maxminddb-mcp\ngo build -o maxminddb-mcp cmd/maxminddb-mcp/main.go\n```\n\n### Basic Configuration\n\nCreate `~/.config/maxminddb-mcp/config.toml`:\n\n```toml\nmode = \"maxmind\"\nauto_update = true\nupdate_interval = \"24h\"\n\n[maxmind]\naccount_id = 123456\nlicense_key = \"your_license_key_here\"\neditions = [\"GeoLite2-City\", \"GeoLite2-Country\", \"GeoLite2-ASN\"]\ndatabase_dir = \"~/.cache/maxminddb-mcp/databases\"\n```\n\n## Client Integration\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Desktop\u003c/summary\u003e\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"maxminddb\": {\n      \"command\": \"maxminddb-mcp\",\n      \"env\": {\n        \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n      }\n    }\n  }\n}\n```\n\nAlternative with existing GeoIP.conf:\n\n```json\n{\n  \"mcpServers\": {\n    \"maxminddb\": {\n      \"command\": \"maxminddb-mcp\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Code CLI\u003c/summary\u003e\n\nAdd the MCP server to Claude Code CLI:\n\n```bash\nclaude mcp add maxminddb maxminddb-mcp\n```\n\nTo use with a custom config:\n\n```bash\nMAXMINDDB_MCP_CONFIG=/path/to/config.toml claude chat\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Code (VS Code Extension)\u003c/summary\u003e\n\nInstall the Claude Code extension and add to VS Code settings:\n\n```json\n{\n  \"claude.mcpServers\": {\n    \"maxminddb\": {\n      \"command\": \"maxminddb-mcp\",\n      \"env\": {\n        \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eContinue\u003c/summary\u003e\n\nInstall the Continue extension and add to your Continue configuration (`~/.continue/config.json`):\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"maxminddb\",\n      \"command\": \"maxminddb-mcp\",\n      \"env\": {\n        \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n      }\n    }\n  ]\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eZed\u003c/summary\u003e\n\nAdd to Zed settings (`~/.config/zed/settings.json`):\n\n```json\n{\n  \"assistant\": {\n    \"mcp_servers\": [\n      {\n        \"name\": \"maxminddb\",\n        \"command\": \"maxminddb-mcp\",\n        \"env\": {\n          \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n        }\n      }\n    ]\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCline\u003c/summary\u003e\n\nInstall Cline and add to VS Code settings:\n\n```json\n{\n  \"cline.mcpServers\": {\n    \"maxminddb\": {\n      \"command\": \"maxminddb-mcp\",\n      \"env\": {\n        \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGemini CLI\u003c/summary\u003e\n\nAdd to your Gemini CLI configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"maxminddb\": {\n      \"command\": \"maxminddb-mcp\",\n      \"env\": {\n        \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n      }\n    }\n  }\n}\n```\n\nSee the [Gemini CLI MCP guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) for more details.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCodex\u003c/summary\u003e\n\nAdd to your Codex configuration file:\n\n```toml\n[mcp_servers.maxminddb]\ncommand = \"maxminddb-mcp\"\nenv = { MAXMINDDB_MCP_CONFIG = \"/path/to/your/config.toml\" }\n```\n\nOr without custom config:\n\n```toml\n[mcp_servers.maxminddb]\ncommand = \"maxminddb-mcp\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSourcegraph Cody\u003c/summary\u003e\n\nAdd to Cody settings:\n\n```json\n{\n  \"cody.experimental.mcp\": {\n    \"servers\": {\n      \"maxminddb\": {\n        \"command\": \"maxminddb-mcp\",\n        \"env\": {\n          \"MAXMINDDB_MCP_CONFIG\": \"/path/to/your/config.toml\"\n        }\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLLM (Simon Willison)\u003c/summary\u003e\n\nInstall the LLM tool and configure MCP:\n\n```bash\n# Install LLM\npip install llm\n\n# Configure MCP server\nllm mcp install maxminddb-mcp --command maxminddb-mcp\n\n# Use with environment variable\nMAXMINDDB_MCP_CONFIG=/path/to/config.toml llm chat -m claude-3.5-sonnet\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePython SDK\u003c/summary\u003e\n\n```bash\npip install mcp\n```\n\n```python\nfrom mcp import ClientSession, StdioServerParameters\n\nasync with ClientSession(\n    StdioServerParameters(\n        command=\"maxminddb-mcp\",\n        env={\"MAXMINDDB_MCP_CONFIG\": \"/path/to/config.toml\"}\n    )\n) as session:\n    await session.initialize()\n    tools = await session.list_tools()\n    result = await session.call_tool(\"lookup_ip\", {\"ip\": \"8.8.8.8\"})\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTypeScript SDK\u003c/summary\u003e\n\n```bash\nnpm install @modelcontextprotocol/sdk\n```\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst transport = new StdioClientTransport({\n  command: \"maxminddb-mcp\",\n  env: { MAXMINDDB_MCP_CONFIG: \"/path/to/config.toml\" },\n});\n\nconst client = new Client(\n  {\n    name: \"maxminddb-client\",\n    version: \"1.0.0\",\n  },\n  { capabilities: {} }\n);\n\nawait client.connect(transport);\nconst result = await client.callTool({\n  name: \"lookup_ip\",\n  arguments: { ip: \"8.8.8.8\" },\n});\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGo SDK\u003c/summary\u003e\n\n```bash\ngo get github.com/mark3labs/mcp-go\n```\n\n```go\nimport (\n    \"github.com/mark3labs/mcp-go/client\"\n    \"github.com/mark3labs/mcp-go/transport/stdio\"\n)\n\ncmd := exec.Command(\"maxminddb-mcp\")\ncmd.Env = append(cmd.Env, \"MAXMINDDB_MCP_CONFIG=/path/to/config.toml\")\n\ntransport := stdio.NewTransport(cmd)\nmcpClient := client.New(transport)\n// ... use client\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCommand Line Testing\u003c/summary\u003e\n\nTest the server directly using JSON-RPC:\n\n```bash\n# List available tools\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | maxminddb-mcp\n\n# Test IP lookup\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"lookup_ip\",\"arguments\":{\"ip\":\"8.8.8.8\"}}}' | maxminddb-mcp\n\n# Pretty output with jq\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | maxminddb-mcp | jq .\n```\n\n\u003c/details\u003e\n\n### Configuration Notes\n\n**Path Requirements**: Ensure `maxminddb-mcp` is in your system PATH or provide the full path to the binary.\n\n**Environment Variables**: All clients support these environment variables:\n\n- `MAXMINDDB_MCP_CONFIG`: Path to configuration file\n- `MAXMINDDB_MCP_LOG_LEVEL`: Logging level (`debug`, `info`, `warn`, `error`)\n- `MAXMINDDB_MCP_LOG_FORMAT`: Log format (`text`, `json`)\n\n**Security**: Store sensitive configuration (API keys) in files with appropriate permissions (600) rather than environment variables in client configs.\n\n## Configuration\n\n### Configuration Modes\n\nThe server supports three configuration modes (checked in order):\n\n1. **Environment variable**: `MAXMINDDB_MCP_CONFIG`\n2. **User config**: `~/.config/maxminddb-mcp/config.toml`\n3. **GeoIP.conf compatibility**: `/etc/GeoIP.conf` or `~/.config/maxminddb-mcp/GeoIP.conf`\n\n### TOML Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003eComplete configuration example\u003c/summary\u003e\n\n```toml\n# Operation mode: \"maxmind\", \"directory\", or \"geoip_compat\"\nmode = \"maxmind\"\n\n# Auto-update settings\nauto_update = true\nupdate_interval = \"24h\"\n\n# Iterator settings\niterator_ttl = \"10m\"\niterator_cleanup_interval = \"1m\"\n\n# Logging (optional)\nlog_level = \"info\"  # debug, info, warn, error\nlog_format = \"text\" # text, json\n\n[maxmind]\n# MaxMind account credentials\naccount_id = 123456\nlicense_key = \"your_license_key_here\"\n\n# Databases to download\neditions = [\n    \"GeoLite2-City\",\n    \"GeoLite2-Country\",\n    \"GeoLite2-ASN\",\n    \"GeoIP2-City\",\n    \"GeoIP2-Country\"\n]\n\n# Storage location\ndatabase_dir = \"~/.cache/maxminddb-mcp/databases\"\n\n# Custom endpoint (optional)\n# endpoint = \"https://updates.maxmind.com\"\n\n[directory]\n# For directory mode - scan these paths for MMDB files\npaths = [\n    \"/path/to/mmdb/files\",\n    \"/another/path\"\n]\n\n[geoip_compat]\n# For GeoIP.conf compatibility mode\nconfig_path = \"/etc/GeoIP.conf\"\ndatabase_dir = \"/var/lib/GeoIP\"\n```\n\n\u003c/details\u003e\n\n#### Configuration Options\n\n**Iterator Settings:**\n\n- `iterator_ttl` (default: \"10m\"): How long idle iterators are kept before cleanup\n- `iterator_cleanup_interval` (default: \"1m\"): How often to check for expired iterators\n\n### GeoIP.conf Compatibility\n\n\u003cdetails\u003e\n\u003csummary\u003eExisting GeoIP.conf users\u003c/summary\u003e\n\nThe server automatically detects and uses existing GeoIP.conf files:\n\n```conf\n# Example GeoIP.conf\nAccountID 123456\nLicenseKey your_license_key_here\nEditionIDs GeoLite2-Country GeoLite2-City GeoLite2-ASN\nDatabaseDirectory /var/lib/GeoIP\n```\n\nNo additional configuration needed - the server will automatically use compatibility mode.\n\n\u003c/details\u003e\n\n## Available Tools\n\n### Core Tools\n\n#### `lookup_ip`\n\nLook up geolocation and network information for a specific IP address.\n\n**Parameters:**\n\n- `ip` (required): IP address to lookup (IPv4 or IPv6)\n- `database` (optional): Specific database filename to query\n\n**Example:**\n\n```json\n{\n  \"name\": \"lookup_ip\",\n  \"arguments\": {\n    \"ip\": \"8.8.8.8\",\n    \"database\": \"GeoLite2-City.mmdb\"\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"ip\": \"8.8.8.8\",\n  \"network\": \"8.8.8.0/24\",\n  \"data\": {\n    \"country\": {\n      \"iso_code\": \"US\",\n      \"names\": { \"en\": \"United States\" }\n    },\n    \"location\": {\n      \"latitude\": 37.4056,\n      \"longitude\": -122.0775\n    }\n  }\n}\n```\n\n#### `lookup_network`\n\nQuery all IP addresses in a network range with powerful filtering capabilities.\n\n**Parameters:**\n\n- `network` (required): CIDR network to scan (e.g., \"192.168.1.0/24\")\n- `database` (optional): Specific database to query\n- `filters` (optional): Array of filter objects. Each object must include `field`, `operator`, and `value`.\n- `filter_mode` (optional): \"and\" (default) or \"or\"\n- `max_results` (optional): Maximum results to return (default: 1000)\n- `iterator_id` (optional): Resume existing iterator\n- `resume_token` (optional): Fallback token for expired iterators\n\n\u003cdetails\u003e\n\u003csummary\u003eFiltering Examples\u003c/summary\u003e\n\n**Filter by country:**\n\n```json\n{\n  \"name\": \"lookup_network\",\n  \"arguments\": {\n    \"network\": \"10.0.0.0/8\",\n    \"filters\": [\n      {\n        \"field\": \"country.iso_code\",\n        \"operator\": \"in\",\n        \"value\": [\"US\", \"CA\", \"MX\"]\n      }\n    ]\n  }\n}\n```\n\n**Filter residential IPs:**\n\n```json\n{\n  \"name\": \"lookup_network\",\n  \"arguments\": {\n    \"network\": \"192.168.0.0/16\",\n    \"filters\": [\n      {\n        \"field\": \"traits.user_type\",\n        \"operator\": \"equals\",\n        \"value\": \"residential\"\n      }\n    ]\n  }\n}\n```\n\nCommon mistakes and validation\n\n- 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\" }`.\n- `filters` must be an array of objects; other types are invalid.\n- `operator` must be supported (see list below). Short aliases (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`) are also accepted.\n\n**Complex filtering (non-proxy IPs):**\n\n```json\n{\n  \"name\": \"lookup_network\",\n  \"arguments\": {\n    \"network\": \"10.0.0.0/24\",\n    \"filters\": [\n      {\n        \"field\": \"traits.is_anonymous_proxy\",\n        \"operator\": \"equals\",\n        \"value\": false\n      },\n      {\n        \"field\": \"traits.is_satellite_provider\",\n        \"operator\": \"equals\",\n        \"value\": false\n      }\n    ],\n    \"filter_mode\": \"and\"\n  }\n}\n```\n\n\u003c/details\u003e\n\n#### `list_databases`\n\nList all available MaxMind databases with metadata.\n\n**Example:**\n\n```json\n{\n  \"name\": \"list_databases\",\n  \"arguments\": {}\n}\n```\n\n**Response:**\n\n```json\n{\n  \"databases\": [\n    {\n      \"name\": \"GeoLite2-City.mmdb\",\n      \"type\": \"City\",\n      \"description\": \"GeoLite2 City Database\",\n      \"last_updated\": \"2024-01-15T10:30:00Z\",\n      \"size\": 67108864\n    }\n  ]\n}\n```\n\n#### `update_databases`\n\nManually trigger database updates (MaxMind/GeoIP modes only).\n\n**Example:**\n\n```json\n{\n  \"name\": \"update_databases\",\n  \"arguments\": {}\n}\n```\n\n### Filter Operators\n\n**Supported Operators:**\n\n- `equals`: Exact match\n- `not_equals`: Not equal to value\n- `in`: Value is in provided array\n- `not_in`: Value is not in provided array\n- `contains`: String contains substring\n- `regex`: Matches regular expression\n- `greater_than`: Numeric comparison\n- `greater_than_or_equal`: Numeric comparison (≥)\n- `less_than`: Numeric comparison\n- `less_than_or_equal`: Numeric comparison (≤)\n- `exists`: Field exists (boolean value)\n\n**Operator Aliases:**\nFor convenience, short operator aliases are supported (case-insensitive):\n\n- `eq` → `equals`\n- `ne` → `not_equals`\n- `gt` → `greater_than`\n- `gte` → `greater_than_or_equal`\n- `lt` → `less_than`\n- `lte` → `less_than_or_equal`\n\n### Error Handling\n\nAll tools return structured error responses with machine-readable error codes:\n\n```json\n{\n  \"error\": {\n    \"code\": \"db_not_found\",\n    \"message\": \"Database not found: invalid_db.mmdb\"\n  }\n}\n```\n\n**Common Error Codes:**\n\n- `db_not_found`: Specified database does not exist\n- `invalid_ip`: IP address format is invalid\n- `invalid_network`: Network CIDR format is invalid\n- `invalid_filter`: Filter validation failed\n- `iterator_not_found`: Iterator ID not found or expired\n- `parse_error`: Failed to parse request parameters\n\n## Advanced Features\n\n### Stateful Iterator System\n\nFor large network queries, the server uses a stateful iterator system:\n\n1. **Fast Path**: Resume active iterations using `iterator_id`\n2. **Resilient Path**: Resume from `resume_token` after expiration\n3. **Automatic Cleanup**: Expired iterators cleaned up after TTL\n4. **Efficient Skip**: Skip to resume point without re-processing\n\n**Example iteration workflow:**\n\n```json\n// First call - creates iterator\n{\n  \"name\": \"lookup_network\",\n  \"arguments\": {\n    \"network\": \"10.0.0.0/8\",\n    \"max_results\": 1000\n  }\n}\n\n// Response includes iterator_id for continuation\n{\n  \"results\": [...],\n  \"iterator_id\": \"iter_abc123\",\n  \"resume_token\": \"eyJ0eXAiOiJKV1Q...\",\n  \"has_more\": true\n}\n\n// Continue with iterator_id (fast path)\n{\n  \"name\": \"lookup_network\",\n  \"arguments\": {\n    \"network\": \"10.0.0.0/8\",\n    \"iterator_id\": \"iter_abc123\",\n    \"max_results\": 1000\n  }\n}\n```\n\n### Auto-updating\n\n\u003cdetails\u003e\n\u003csummary\u003eAutomatic database updates\u003c/summary\u003e\n\nConfigure automatic updates in your TOML config:\n\n```toml\nauto_update = true\nupdate_interval = \"24h\"  # Check every 24 hours\n```\n\nThe server will:\n\n- Check for database updates on the specified interval\n- Download only if MD5 checksums have changed\n- Gracefully reload databases without interrupting active queries\n- Log update status and any errors\n\n**Manual Updates:**\nUse the `update_databases` tool to trigger immediate updates.\n\n\u003c/details\u003e\n\n### File Watching\n\n\u003cdetails\u003e\n\u003csummary\u003eDirectory mode with file watching\u003c/summary\u003e\n\nIn directory mode, the server watches for filesystem changes:\n\n```toml\nmode = \"directory\"\n\n[directory]\npaths = [\"/path/to/mmdb/files\"]\n```\n\n**Supported events:**\n\n- **Create**: Automatically loads new MMDB files\n- **Write**: Reloads modified databases\n- **Remove**: Removes databases from available list\n- **Rename**: Handles file renames gracefully\n\n**Subdirectory support:** Recursively watches all subdirectories for MMDB files.\n\n\u003c/details\u003e\n\n## Troubleshooting\n\n### Common Issues\n\n\u003cdetails\u003e\n\u003csummary\u003eServer not starting\u003c/summary\u003e\n\n**Check configuration:**\n\n```bash\n# Verify config file syntax\nmaxminddb-mcp --help\n\n# Test configuration loading\nMAXMINDDB_MCP_LOG_LEVEL=debug maxminddb-mcp\n```\n\n**Common causes:**\n\n- Invalid TOML syntax in config file\n- Missing MaxMind credentials\n- Insufficient file permissions\n- Invalid database directory path\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDatabase loading failures\u003c/summary\u003e\n\n**Check database status:**\n\n```bash\n# Enable debug logging\nMAXMINDDB_MCP_LOG_LEVEL=debug maxminddb-mcp\n```\n\n**Common causes:**\n\n- Corrupt MMDB files (check file integrity)\n- Insufficient disk space for downloads\n- Network connectivity issues to updates.maxmind.com\n- Expired MaxMind subscription\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Desktop integration\u003c/summary\u003e\n\n**Verify server path:**\n\n```bash\n# Check server is in PATH\nwhich maxminddb-mcp\n\n# Test server directly\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' | maxminddb-mcp\n```\n\n**Configuration file locations:**\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n\u003c/details\u003e\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n```bash\n# Environment variables\nMAXMINDDB_MCP_LOG_LEVEL=debug\nMAXMINDDB_MCP_LOG_FORMAT=json\n\n# Or in config.toml\nlog_level = \"debug\"\nlog_format = \"json\"\n```\n\n### Configuration Validation\n\nThe server validates all configuration on startup and provides detailed error messages:\n\n- Required fields for each mode\n- Valid duration formats (e.g., \"24h\", \"10m\")\n- Path expansion and validation\n- Network connectivity checks\n\n## Performance Considerations\n\n### Memory Usage\n\n- **Base memory**: ~50MB\n- **Database storage**: 100-500MB depending on editions\n\n### Optimization Tips\n\n- Avoid unnecessary iterations: use selective filters and appropriate `max_results`\n- **Database selection**: Only download needed editions to reduce memory usage\n- **Update frequency**: Balance freshness vs. network usage with `update_interval`\n- **Filter efficiency**: Use selective filters early to reduce processing\n\n### Resource Limits\n\n- **Concurrent iterators**: No hard limit, managed by TTL cleanup\n- **Network query size**: Limited by available memory and `max_results`\n- **Database file size**: Supports databases up to several GB\n\n## License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and suggest improvements.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/oschwald/maxminddb-mcp/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/oschwald/maxminddb-mcp/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foschwald%2Fmaxminddb-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foschwald%2Fmaxminddb-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foschwald%2Fmaxminddb-mcp/lists"}