Skip to main content
Glama

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: ZimAgent

运行

将你的 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" }
    }
  }
}

工具

始终可用:

工具

功能

list_libraries

清单:列出每个 ZIM 的类型、标题、语言和聚合能力(general_knowledge、medical、maps 等)。请先调用此工具。

search

跨所有 ZIM 进行全文搜索(存在时使用 libzim 的 Xapian 索引,否则回退到标题前缀建议)。接受可选的 kind 过滤器。

get_article

按路径获取条目;HTML 已去除导航框/信息框/脚本冗余,以便 LLM 看到干净的文本。

get_main_page

获取单个 ZIM 或所有已加载 ZIM 的主页。

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

工具

功能

plan_driving_route

在 streetzim 路由图上进行 A* 搜索。输入:两个 lat/lon 对。输出:总距离、持续时间、折线以及按街道名称合并的道路段列表。

geocode

使用 streetzim 的前缀分块搜索索引将地点/地址字符串解析为坐标。

route_from_places

便利工具:先对两个端点进行地理编码,然后规划路线。

路由器中的成本/启发式算法与 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。

Available Tools

4 tools
get_articleA

Fetch a single article by path, as plain text ready for reading.

Args: path: the ZIM entry path (as returned in search results, e.g. A/Aspirin). zim: optional filename or path of the ZIM to read from. If omitted, all loaded ZIMs are tried in scan order.

Inputs: path (required), zim.

get_main_pageB

Fetch the main/home page of a ZIM. If no zim name is given, returns the main page of every loaded ZIM.

Inputs: zim.

list_librariesA

Inventory the ZIM archives this server can read.

Returns a list of archives with their kind (wikipedia / mdwiki / streetzim / generic), metadata, and the aggregate capabilities exposed (e.g. plan_route is only present when a streetzim ZIM is loaded). Call this first so you know what sources and tools are available.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_article fetches a specific article, get_main_page retrieves the main page, list_libraries inventories available archives, and search performs full-text queries. The descriptions clearly differentiate their functions, eliminating any ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_article, get_main_page, list_libraries, search), with 'search' being a concise exception that still fits the verb-first style. The naming is uniform and predictable across the set.

    Tool Count5/5

    With 4 tools, this server is well-scoped for its purpose of accessing ZIM archives. Each tool earns its place by covering essential operations: inventorying sources, retrieving content (specific articles and main pages), and searching. The count is neither too sparse nor bloated.

    Completeness5/5

    The tool set provides complete coverage for the domain of reading and searching ZIM archives. It includes discovery (list_libraries), content retrieval (get_article, get_main_page), and search capabilities, with no obvious gaps. Agents can navigate from listing to fetching or searching seamlessly.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      An MCP server that enables interaction with Kiwix HTTP servers to browse, search, and retrieve content from offline ZIM books like Wikipedia. It provides tools for listing available library resources and fetching full-text articles as plain text.
      3
      10
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables offline CRUD and semantic search on Wikipedia ZIM archives via MCP tools for reading, writing, editing, deleting, and searching articles.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for reading and searching ZIM archives, optimized for single-user deployments with a persistent Wikipedia archive.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive local offline MCP server with over 300 tools for file operations, office documents, PDFs, code execution, databases, web browsing, memory, and cognitive functions, designed to work offline except for web search and email.
      MIT