Maxminddb Mcp

位置 Go

🚀 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）的文件中，而不是客户端配置的环境变量中。

📚 详细文档

配置模式

服务器支持三种配置模式（按顺序检查）：

环境变量：MAXMINDDB_MCP_CONFIG
用户配置：~/.config/maxminddb-mcp/config.toml
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：解析请求参数失败

高级功能

有状态迭代器系统

对于大型网络查询，服务器使用有状态迭代器系统：

快速路径：使用 iterator_id 恢复活动迭代。
弹性路径：在迭代器过期后，使用 resume_token 恢复。
自动清理：过期迭代器在 TTL 后自动清理。
高效跳过：跳过到恢复点，无需重新处理。

示例迭代工作流程

// 第一次调用 - 创建迭代器
{
"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

0 条评论
分类：位置

Maxminddb Mcp

🚀 MaxMindDB MCP Server

✨ 主要特性

🚀 快速开始

📦 安装指南

选项 1：通过 Go 安装

选项 2：从源代码构建

基本配置

💻 使用示例

客户端集成

Claude Desktop

Claude Code CLI

Claude Code (VS Code Extension)

Continue

Zed

Cline

Gemini CLI

Codex

Sourcegraph Cody

LLM (Simon Willison)

Python SDK

TypeScript SDK

Go SDK

命令行测试

配置说明

📚 详细文档

配置模式

TOML 配置

完整配置示例

配置选项

GeoIP.conf 兼容性

已有 GeoIP.conf 文件的用户

🔧 技术细节

可用工具

lookup_ip

lookup_network

过滤示例

list_databases

update_databases

过滤运算符

支持的运算符

运算符别名

错误处理

常见错误代码

高级功能

有状态迭代器系统

示例迭代工作流程

自动更新

手动更新

文件监控

支持的事件

子目录支持

故障排除

常见问题

服务器无法启动

常见原因

数据库加载失败

常见原因

Claude Desktop 集成问题

配置文件位置

调试模式

配置验证

性能考虑

内存使用

优化建议

资源限制

📄 许可证

贡献说明

支持渠道

0 个评论

相似服务问题

热议话题 »

`lookup_ip`

`lookup_network`

`list_databases`

`update_databases`