mcpzim

一个 MCP 服务器，使一组离线 ZIM 文件可供本地 LLM 代理使用。将其指向一个 ZIM 目录，服务器将执行以下操作：

• 清点目录内容 (list_libraries) 并根据加载的内容发布聚合能力（通用知识、医学知识、地图/路线）。

• 公开跨所有 ZIM 的搜索和文章检索功能 (search, get_article, get_main_page)。

• 当检测到使用 --routing 构建的 streetzim ZIM 时，它还会额外公开 plan_driving_route、geocode 和 route_from_places，以便本地代理可以询问 “给我一条从 A 到 B 的驾驶路线” 并获得逐条街道的导航、距离和预计时间。

设计原则是机会主义能力：从一个维基百科 ZIM 开始，你就会得到一个维基百科服务器。放入 mdwiki_en_all_*.zim，它还可以回答医学问题。放入一个 streetzim ZIM，它还可以为该 ZIM 覆盖的区域规划驾驶路线。工具仅在底层数据存在时才会出现，因此代理的工具列表永远不会谎报服务器的功能。

安装

需要 Python 3.10+。

pip install mcpzim               # once published
# or, from a checkout:
pip install -e .

libzim 是一个原生 wheel；macOS (x86_64/arm64)、Linux (x86_64/aarch64, glibc 和 musl) 和 Windows x64 都有预构建的 wheel。在其他平台上，pip 将从源代码构建，你需要一个 C++ 工具链。

Related MCP server: kiwix-mcp

运行

将你的 ZIM 文件放入一个目录并运行：

export ZIM_DIR=~/zims
mcpzim                           # stdio transport (Claude Desktop / Code)
mcpzim ~/zims/wikipedia.zim ~/zims/streetzim_ma.zim   # explicit paths
mcpzim --transport streamable-http --host 0.0.0.0 --port 8765  # LAN

添加到 ~/.config/claude-desktop/claude_desktop_config.json（或你的 MCP 客户端对应的配置文件）：

{
  "mcpServers": {
    "mcpzim": {
      "command": "mcpzim",
      "env": { "ZIM_DIR": "/Users/me/zims" }
    }
  }
}

工具

始终可用：

仅在加载了包含路由数据的 streetzim ZIM 时出现：

路由器中的成本/启发式算法与 streetzim 的 JS 查看器完全一致： edge_cost = distance_m / (speed_kmh / 3.6) 且 heuristic = haversine / (100/3.6)，因此结果与浏览器内查看器产生的结果相同。

支持的 ZIM

类型检测在扫描时运行，并结合了文件名前缀、ZIM 的 Name / Tags / Creator / Publisher 元数据以及归档内的签名条目。开箱即用：

• Wikipedia — 任何 wikipedia_*.zim (Creator: Wikipedia, 标记为 wikipedia)。

• mdwiki — 来自 WikiProjectMed Foundation 的 mdwiki_*.zim (标记为 mdwiki / medical)。

• streetzim — 通过归档内是否存在 routing-data/graph.bin 或 map-config.json 进行检测。

• generic — 其他任何内容（*.zim 仍然会被服务；仅适用 ZimKind.GENERIC 默认工具集）。

示例会话

> list_libraries
{"zims": [
   {"path": ".../wikipedia_en_all_nopic_2026-03.zim", "kind": "wikipedia", ...},
   {"path": ".../mdwiki_en_all_2026-03.zim", "kind": "mdwiki", ...},
   {"path": ".../streetzim_ma.zim", "kind": "streetzim", "has_routing": true, ...}
 ],
 "by_kind": {"wikipedia": 1, "mdwiki": 1, "streetzim": 1},
 "capabilities": ["encyclopedia", "general_knowledge", "geocode",
                  "get_article", "list_libraries", "maps", "medical",
                  "plan_route", "search"]}

> route_from_places {"origin": "Boston Common", "destination": "Fenway Park"}
{"origin_resolved": {"name": "Boston Common", "lat": 42.3554, "lon": -71.0655, ...},
 "destination_resolved": {"name": "Fenway Park", "lat": 42.3467, "lon": -71.0972, ...},
 "distance_km": 3.27, "duration_min": 9.4,
 "roads": [
    {"name": "Beacon Street", "distance_m": 412.3, "duration_s": 44.0},
    ...
 ],
 "turn_by_turn": ["Beacon Street for 0.41 km (~0.7 min)", ...],
 "polyline": [[42.3554, -71.0655], ...]}

移动端

诚实的回答是：目前在 iOS 上运行原生 Python + libzim 很痛苦，因为 python-libzim 没有 iOS wheel，你必须自己交叉编译 C++ libzim。按工作量排序的实用选项：

1. 局域网桥接（最简单，现在即可使用）。 在你网络中的机器（或树莓派）上运行 mcpzim --transport streamable-http --host 0.0.0.0。将你的移动代理指向它。ZIM 数据保留在家庭服务器上；你的手机只是看到一个功能丰富的 MCP 端点。这在没有移动端代码的情况下今天就可以工作。

2. 通过 Termux 在 Android 上运行。 在 Termux 中执行 pkg install python clang && pip install mcpzim 会从源代码构建 libzim。在设备上运行，通过 stdio（给本地代理进程）或 localhost 上的 streamable-http 暴露给应用内客户端。

3. Swift/Kotlin 移植。 SZRG v2 路由格式和 ZIM 访问层都是刻意设计的简单。一个通过 Swift 绑定调用 C++ libzim 的 Swift MCP 模块（正如 Kiwix iOS 已经做的那样）可以暴露与此 Python 服务器相同的工具界面。这是希望拥有进程内 MCP 工具提供程序的 iOS 聊天应用的最佳路径。

4. Kiwix-serve 桥接。 Kiwix 移动应用已经嵌入了一个本地 HTTP 服务器；一种不直接打开 ZIM 而是代理到 http://localhost:port/ 的替代 mcpzim 模式可以在任何运行 Kiwix 的地方工作。（尚未实现 — 欢迎提交 PR。）

开发

pip install -e '.[dev]'
pytest

测试不需要任何真实的 ZIM 文件；路由测试使用 mcpzim.routing.encode_graph_v2 在内存中构建一个微小的 SZRG v2 图，库测试直接对分类器进行练习。

许可证

MIT。