Maxminddb MCP

🚀 MaxMindDB MCP Server

MaxMindDB MCP Server 是一個強大的模型上下文協議（MCP）服務器，它通過 MaxMindDB 數據庫提供全面的地理位置和網絡情報。支持對 GeoIP2、GeoLite2 和自定義 MMDB 文件進行查詢，並具備高級過濾、有狀態迭代和自動更新等功能。

⚠️ 重要提示

這是一個非官方項目，未得到 MaxMind Inc. 的認可。此 MCP 服務器是獨立實現的。如需官方 MaxMind 產品和支持，請訪問 maxmind.com。

✨ 主要特性

• 多數據源支持：支持 MaxMind 賬戶、目錄掃描以及與 GeoIP.conf 兼容。
• 高級過濾功能：可通過 11 種以上運算符（如等於、正則表達式、比較等）對任意 MMDB 字段進行查詢。
• 有狀態迭代：使用可恢復的迭代器高效處理大型網絡範圍。
• 自動更新：可自動從 MaxMind 下載和更新數據庫。
• 文件監控：動態加載新的或更新後的數據庫文件。
• 靈活配置：支持使用 TOML 配置文件，同時提供 GeoIP.conf 回退支持。

🚀 快速開始

📦 安裝指南

選項 1：通過 Go 安裝

go install github.com/oschwald/maxminddb-mcp/cmd/maxminddb-mcp@latest

選項 2：從源代碼構建

git clone https://github.com/oschwald/maxminddb-mcp.git
cd maxminddb-mcp
go build -o maxminddb-mcp cmd/maxminddb-mcp/main.go

基本配置

創建 ~/.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"

💻 使用示例

客戶端集成

Claude Desktop

將以下內容添加到 Claude Desktop 配置文件中：

• 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"
      }
    }
  }
}

若已有 GeoIP.conf 文件，可使用以下配置：

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

Claude Code CLI

將 MCP 服務器添加到 Claude Code CLI：

claude mcp add maxminddb maxminddb-mcp

若要使用自定義配置：

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

Claude Code (VS Code Extension)

安裝 Claude Code 擴展並添加到 VS Code 設置中：

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

Continue

安裝 Continue 擴展並添加到 Continue 配置文件 (~/.continue/config.json) 中：

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

Zed

將以下內容添加到 Zed 設置 (~/.config/zed/settings.json) 中：

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

Cline

安裝 Cline 並添加到 VS Code 設置中：

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

Gemini CLI

將以下內容添加到 Gemini CLI 配置文件中：

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

更多詳細信息請參閱 Gemini CLI MCP 指南。

Codex

將以下內容添加到 Codex 配置文件中：

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

若不使用自定義配置：

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

Sourcegraph Cody

將以下內容添加到 Cody 設置中：

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

LLM (Simon Willison)

安裝 LLM 工具並配置 MCP：

# 安裝 LLM
pip install llm

# 配置 MCP 服務器
llm mcp install maxminddb-mcp --command maxminddb-mcp

# 使用環境變量
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)
// ... 使用客戶端

命令行測試

使用 JSON-RPC 直接測試服務器：

# 列出可用工具
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | maxminddb-mcp

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

# 使用 jq 進行美化輸出
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | maxminddb-mcp | jq .

配置說明

• 路徑要求：確保 maxminddb-mcp 在系統路徑中，或者提供二進制文件的完整路徑。
• 環境變量：所有客戶端都支持以下環境變量：
  • MAXMINDDB_MCP_CONFIG：配置文件的路徑。
  • MAXMINDDB_MCP_LOG_LEVEL：日誌級別 (debug, info, warn, error)。
  • MAXMINDDB_MCP_LOG_FORMAT：日誌格式 (text, json)。
• 安全建議：將敏感配置（如 API 密鑰）存儲在具有適當權限（600）的文件中，而不是客戶端配置的環境變量中。

📚 詳細文檔

配置模式

服務器支持三種配置模式（按順序檢查）：

1. 環境變量：MAXMINDDB_MCP_CONFIG
2. 用戶配置：~/.config/maxminddb-mcp/config.toml
3. GeoIP.conf 兼容性：/etc/GeoIP.conf 或 ~/.config/maxminddb-mcp/GeoIP.conf

TOML 配置

完整配置示例

# 操作模式: "maxmind", "directory", 或 "geoip_compat"
mode = "maxmind"

# 自動更新設置
auto_update = true
update_interval = "24h"

# 迭代器設置
iterator_ttl = "10m"
iterator_cleanup_interval = "1m"

# 日誌記錄 (可選)
log_level = "info"  # debug, info, warn, error
log_format = "text" # text, json

[maxmind]
# MaxMind 賬戶憑證
account_id = 123456
license_key = "your_license_key_here"

# 要下載的數據庫
editions = [
    "GeoLite2-City",
    "GeoLite2-Country",
    "GeoLite2-ASN",
    "GeoIP2-City",
    "GeoIP2-Country"
]

# 存儲位置
database_dir = "~/.cache/maxminddb-mcp/databases"

# 自定義端點 (可選)
# endpoint = "https://updates.maxmind.com"

[directory]
# 目錄模式 - 掃描這些路徑以查找 MMDB 文件
paths = [
    "/path/to/mmdb/files",
    "/another/path"
]

[geoip_compat]
# GeoIP.conf 兼容模式
config_path = "/etc/GeoIP.conf"
database_dir = "/var/lib/GeoIP"

配置選項

• 迭代器設置：
  • iterator_ttl（默認值："10m"）：空閒迭代器在清理前的保留時間。
  • iterator_cleanup_interval（默認值："1m"）：檢查過期迭代器的頻率。

GeoIP.conf 兼容性

已有 GeoIP.conf 文件的用戶

服務器會自動檢測並使用現有的 GeoIP.conf 文件：

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

無需額外配置，服務器將自動使用兼容模式。

🔧 技術細節

可用工具

lookup_ip

查找特定 IP 地址的地理位置和網絡信息。

• 參數：
  • ip（必需）：要查找的 IP 地址（IPv4 或 IPv6）。
  • database（可選）：要查詢的特定數據庫文件名。
• 示例：

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

• 響應：

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

使用強大的過濾功能查詢網絡範圍內的所有 IP 地址。

• 參數：
  • network（必需）：要掃描的 CIDR 網絡（例如，"192.168.1.0/24"）。
  • database（可選）：要查詢的特定數據庫。
  • filters（可選）：過濾對象數組。每個對象必須包含 field、operator 和 value。
  • filter_mode（可選）："and"（默認）或 "or"。
  • max_results（可選）：返回的最大結果數（默認值：1000）。
  • iterator_id（可選）：恢復現有迭代器。
  • resume_token（可選）：過期迭代器的備用令牌。

過濾示例

• 按國家過濾：

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

• 過濾住宅 IP：

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

常見錯誤和驗證：

• 不要將過濾器作為字符串傳遞，如 "traits.user_type=residential"。服務器會拒絕此類請求，並提示使用對象：{ "field": "traits.user_type", "operator": "equals", "value": "residential" }。
• filters 必須是對象數組，其他類型無效。
• operator 必須是支持的運算符（見下文列表）。短別名 (eq, ne, gt, gte, lt, lte) 也被接受。
• 複雜過濾（非代理 IP）：

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

列出所有可用的 MaxMind 數據庫及其元數據。

• 示例：

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

• 響應：

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

update_databases

手動觸發數據庫更新（僅適用於 MaxMind/GeoIP 模式）。

• 示例：

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

過濾運算符

支持的運算符

• equals：精確匹配
• not_equals：不等於指定值
• in：值在提供的數組中
• not_in：值不在提供的數組中
• contains：字符串包含子字符串
• regex：匹配正則表達式
• greater_than：數值比較
• greater_than_or_equal：數值比較（≥）
• less_than：數值比較
• less_than_or_equal：數值比較（≤）
• exists：字段存在（布爾值）

運算符別名

為方便起見，支持短運算符別名（不區分大小寫）：

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

錯誤處理

所有工具都返回結構化的錯誤響應，包含機器可讀的錯誤代碼：

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

常見錯誤代碼

• db_not_found：指定的數據庫不存在
• invalid_ip：IP 地址格式無效
• invalid_network：網絡 CIDR 格式無效
• invalid_filter：過濾器驗證失敗
• iterator_not_found：迭代器 ID 未找到或已過期
• parse_error：解析請求參數失敗

高級功能

有狀態迭代器系統

對於大型網絡查詢，服務器使用有狀態迭代器系統：

1. 快速路徑：使用 iterator_id 恢復活動迭代。
2. 彈性路徑：在迭代器過期後，使用 resume_token 恢復。
3. 自動清理：過期迭代器在 TTL 後自動清理。
4. 高效跳過：跳過到恢復點，無需重新處理。

示例迭代工作流程

// 第一次調用 - 創建迭代器
{
  "name": "lookup_network",
  "arguments": {
    "network": "10.0.0.0/8",
    "max_results": 1000
  }
}

// 響應中包含用於繼續的 iterator_id
{
  "results": [...],
  "iterator_id": "iter_abc123",
  "resume_token": "eyJ0eXAiOiJKV1Q...",
  "has_more": true
}

// 使用 iterator_id 繼續（快速路徑）
{
  "name": "lookup_network",
  "arguments": {
    "network": "10.0.0.0/8",
    "iterator_id": "iter_abc123",
    "max_results": 1000
  }
}

自動更新

在 TOML 配置中配置自動更新：

auto_update = true
update_interval = "24h"  # 每 24 小時檢查一次

服務器將：

• 按指定間隔檢查數據庫更新。
• 僅在 MD5 校驗和發生變化時下載。
• 優雅地重新加載數據庫，不中斷活動查詢。
• 記錄更新狀態和任何錯誤。

手動更新

使用 update_databases 工具觸發立即更新。

文件監控

在目錄模式下，服務器監控文件系統變化：

mode = "directory"

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

支持的事件

• 創建：自動加載新的 MMDB 文件。
• 寫入：重新加載修改後的數據庫。
• 刪除：從可用列表中移除數據庫。
• 重命名：優雅處理文件重命名。

子目錄支持

遞歸監控所有子目錄中的 MMDB 文件。

故障排除

常見問題

服務器無法啟動

• 檢查配置：

# 驗證配置文件語法
maxminddb-mcp --help

# 測試配置加載
MAXMINDDB_MCP_LOG_LEVEL=debug maxminddb-mcp

常見原因

• 配置文件中 TOML 語法無效。
• 缺少 MaxMind 憑證。
• 文件權限不足。
• 數據庫目錄路徑無效。

數據庫加載失敗

• 檢查數據庫狀態：

# 啟用調試日誌
MAXMINDDB_MCP_LOG_LEVEL=debug maxminddb-mcp

常見原因

• MMDB 文件損壞（檢查文件完整性）。
• 下載磁盤空間不足。
• 與 updates.maxmind.com 的網絡連接問題。
• MaxMind 訂閱過期。

Claude Desktop 集成問題

• 驗證服務器路徑：

# 檢查服務器是否在 PATH 中
which maxminddb-mcp

# 直接測試服務器
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | maxminddb-mcp

配置文件位置

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

調試模式

啟用詳細日誌以進行故障排除：

# 環境變量
MAXMINDDB_MCP_LOG_LEVEL=debug
MAXMINDDB_MCP_LOG_FORMAT=json

# 或在 config.toml 中
log_level = "debug"
log_format = "json"

配置驗證

服務器在啟動時驗證所有配置，並提供詳細的錯誤消息：

• 每種模式的必需字段。
• 有效的持續時間格式（例如，"24h", "10m"）。
• 路徑擴展和驗證。
• 網絡連接檢查。

性能考慮

內存使用

• 基礎內存：約 50MB
• 數據庫存儲：根據版本不同，為 100 - 500MB

優化建議

• 避免不必要的迭代：使用選擇性過濾器和適當的 max_results。
• 數據庫選擇：僅下載所需版本，以減少內存使用。
• 更新頻率：通過 update_interval 平衡數據新鮮度和網絡使用。
• 過濾效率：儘早使用選擇性過濾器，以減少處理量。

資源限制

• 併發迭代器：無硬限制，由 TTL 清理管理。
• 網絡查詢大小：受可用內存和 max_results 限制。
• 數據庫文件大小：支持最大數 GB 的數據庫。

📄 許可證

本項目採用 ISC 許可證，請參閱 LICENSE 文件獲取詳細信息。

貢獻說明

歡迎貢獻代碼！請閱讀我們的 貢獻指南，瞭解如何提交拉取請求、報告問題和提出改進建議。

支持渠道

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions