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