openzim-mcp

OpenZIM MCP 服务

将静态 ZIM 存档转化为面向 AI 模型的动态知识引擎

---

✨ 亮点。 精简的 8 个工具高级接口（zim_query、zim_search、zim_get、zim_get_section、zim_browse、zim_metadata、zim_links、zim_health），架构小巧，适合小型模型调度；也可选择单工具 Simple 模式进行自然语言查询。存档类型预设会针对不同来源（Wikipedia、Stack Exchange、……）自动调整检索，入站链接发现可回答“哪些内容链接到这里”，而原生 libzim 检查可验证和检查任何存档。现已上线 Smithery 和官方 MCP Registry。版本说明 → 文档 →

OpenZIM MCP 是一款现代、安全、高性能的模型上下文协议服务，可让 AI 模型以结构化方式离线访问 ZIM 格式知识存档，包括 Wikipedia、Wiktionary、Stack Exchange，以及整个 Kiwix Library。

它专为研究助手、知识聊天机器人和内容分析系统打造，能让它们智能地访问海量知识库，而不只是获取原始文本转储。它支持按命名空间（文章、元数据、媒体）智能导航、感知结构的检索（章节、目录、相关文章）、带建议的全文搜索和多存档搜索，以及用于映射内容关系的链接图提取。缓存和分页操作让海量存档也能保持响应迅速；全面的输入验证和路径遍历防护则确保安全。

内置 Streamable HTTP 传输、带实时变更通知的逐条目 MCP 资源，以及 Simple / Advanced 双模式。

安装

# uv (recommended — isolated CLI tool)
uv tool install openzim-mcp

# pip
pip install openzim-mcp

# Docker (multi-arch image, ghcr.io) — runs as a local stdio MCP server
docker pull ghcr.io/cameronrye/openzim-mcp
docker run -i --rm -v ~/zim-files:/data ghcr.io/cameronrye/openzim-mcp

容器默认使用 stdio 传输，因此 docker run -i 会通过标准输入/输出进行 MCP 通信——像配置二进制文件一样将它接入 MCP 客户端（参见快速开始）。如需运行长期服务的 HTTP 服务（支持 bearer 身份验证、CORS 和健康检查端点），请在运行时启用：-e OPENZIM_MCP_TRANSPORT=http -e OPENZIM_MCP_HOST=0.0.0.0 -e OPENZIM_MCP_AUTH_TOKEN=… -p 8000:8000；请参阅 HTTP & Docker 部署。

验证安装：

openzim-mcp --help

获取你的第一个 ZIM 存档

没有可供读取的存档，服务就无法运行。获取一个真实存档——这是 openZIM 项目自带测试套件中的一个 13.6 MB 气候变化主题英文维基百科摘录。无需账户，也无需安装任何内容：

mkdir -p ~/zim-files
curl -fsSL -o ~/zim-files/wikipedia_en_climate_change_mini_2024-06.zim \
  https://raw.githubusercontent.com/openzim/zim-testing-suite/main/data/withns/wikipedia_en_climate_change_mini_2024-06.zim

~/zim-files 是下方所有示例中传给服务的目录——服务会自行展开 ~，因此无论从 shell 还是客户端配置文件中使用都适用。对于完整存档——维基百科、维基词典、Stack Exchange 等，大小从数百 MB 到数十 GB 不等——请浏览 browse.library.kiwix.org，并将 .zim 文件保存到同一目录中。更多详情，包括校验和以及 Windows PowerShell 等效命令，请参阅：快速开始。

Smithery 和一键安装

OpenZIM MCP 已列入 Smithery 注册表和官方 MCP 注册表（名称为 io.github.cameronrye/openzim-mcp）。使用 Smithery CLI 将其添加到 MCP 客户端：

npx @smithery/cli mcp add rye/openzim-mcp --client claude

如需一键安装 Claude Desktop 扩展，请从最新版本下载 openzim-mcp-<version>.mcpb 资源文件（以及对应的 .sha256 文件），然后双击。该扩展包会启动固定版本的 uvx openzim-mcp@<version>（因此主机需要安装 uv），并提示你选择 ZIM 目录。维护者运行手册：docs/distribution.md。

快速开始

以简单模式运行服务（默认模式——提供一个自然语言工具 zim_query）：

openzim-mcp ~/zim-files

将其接入 MCP 客户端。以下是 Claude Desktop 的 claude_desktop_config.json 示例（任何支持 stdio 的 MCP 客户端都可以采用相同方式）：

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "uvx",
      "args": ["openzim-mcp", "~/zim-files"]
    }
  }
}

客户端连接后，向你的大模型提问：“总结一下光合作用这篇文章”——zim_query 会自动调用合适的底层工具。

如需完全控制，请以高级模式运行，以提供全部 8 个专用工具：

{
  "mcpServers": {
    "openzim-mcp-advanced": {
      "command": "uvx",
      "args": ["openzim-mcp", "--mode", "advanced", "~/zim-files"]
    }
  }
}

有关 HTTP 传输（支持 bearer 身份验证、CORS 和健康检查端点的长期服务），请参阅 HTTP & Docker 部署。

亮点

• 8 个高级工具 — zim_query、zim_search、zim_get、zim_get_section、zim_browse、zim_metadata、zim_links、zim_health。工具数量从 22 个降至 8 个；高级模式的架构从约 36KB 缩减至约 24.1KB，摆脱 MCP Tax 带来的痛点。API 参考 →
• Streamable HTTP 传输 — bearer-token 身份验证、CORS、健康检查端点、多架构 Docker 镜像。HTTP 与 Docker 部署 →
• 按条目提供 MCP 资源并支持订阅 — zim://{name}/entry/{path}，使用原生 MIME 类型；客户端打开 subscriptions/listen 流后，当 ZIM 出现或消失时会收到 resources/list_changed，当 ZIM 被替换时会收到 resources/updated。资源、提示词与订阅 →
• 简单模式下的 zim_query — 一个自然语言工具，可分派到正确的操作，并针对小型模型部署目标进行调优。快速入门 →
• 存档类型预设 — OpenZIM MCP 可检测存档类型（Wikipedia、Stack Exchange 等），并针对该类型自动调优检索和摘要功能。例如，Stack Exchange 转储会呈现为清晰的问答内容，而不是杂乱的投票分数。操作人员可以通过 TOML 文件（OPENZIM_MCP_PRESETS_OVERRIDE_PATH）覆盖随附的默认值。
• 原生 libzim 检查 — zim_health(zim_file_path=...) 会验证存档完整性（Archive.check() + 校验和），zim_metadata 则会报告存档标识、全文／标题索引功能，以及 M/Counter MIME 类型细分信息。API 参考 →
• 发现入站链接（“哪些页面链接到此处”） — zim_links(direction="inbound") 会返回链接到某个条目的页面，并按链接页面的重要性排序。需要预先构建 sidecar 文件：openzim-mcp build link-graph <archive>.zim（会在存档旁写入 <archive>.zim.linkgraph.sqlite）。API 参考 →

模式

OpenZIM MCP 提供两种模式；每个客户端选择一种。

简单模式（默认）提供单个智能工具 zim_query，用于解析自然语言请求并分派到正确的底层操作。专为小型模型部署目标打造——网络传输负载极小，分派在服务端完成，而非在大模型上下文中进行。除非有特定原因选择其他模式，否则请从此模式开始。

高级模式提供全部 8 个专用工具（zim_query、zim_search、zim_get、zim_get_section、zim_browse、zim_metadata、zim_links、zim_health），以及 3 个 MCP 提示词（/research、/summarize、/explore）和按条目提供的资源。专为能够可靠地处理完整架构分派任务的大型模型，以及需要精细控制分页、命名空间浏览和链接图提取的客户端打造。

经验法则：参数量 ≤ 13B 的模型适合使用简单模式；更大的模型（Claude Sonnet/Opus、GPT-4o 级别、Llama 70B+）可直接分派到高级模式。有关如何选择的指导，请参阅 LLM 集成模式。

文档

完整文档请访问 https://cameronrye.github.io/openzim-mcp/docs/。

分组	页面
开始使用	简介 · 安装 · 快速入门 · ZIM 概念 · 大模型集成模式 · 示例讲解
概念	智能检索 · 搜索重排序 · 架构概览
参考	API 参考 · 配置 · 资源、提示词与订阅 · 命令行参考
运维	HTTP 和 Docker 部署 · 性能优化 · 安全最佳实践 · 故障排除 · 常见问题 · 升级

项目状态

v3.4.0 是当前版本（2026-10-25）。
v2.0.0 GA 于 2026-05-27 发布。根据 SECURITY.md，v1.x 的维护期已于 v2.5.0 发布时结束（2026-06-18）；所有活跃开发都在当前主版本系列上进行。v3.0.0 对 HTTP 订阅客户端而言是一个不兼容更新：不再提供 resources/subscribe/unsubscribe 服务——实时更新通过 2026-07-28 协议修订版中的 subscriptions/listen 传递——且必须重新构建由 2.x 生成的链接图 sidecar。工具、资源和提示词均未改变，旧版握手客户端仍可正常工作。详情请参阅 CHANGELOG.md，逐步说明请参阅升级指南。

贡献

有关开发环境设置、测试命令、代码风格和发布流程，请参阅 CONTRIBUTING.md。

安全

有关漏洞披露政策，请参阅 SECURITY.md。目前没有已知 CVE。

许可证

MIT。请参阅 LICENSE。

致谢

• 感谢 openZIM 和 Kiwix 提供 ZIM 格式和 libzim 库
• 感谢 Model Context Protocol 提供开放的客户端-服务端协议
• 感谢开源社区和贡献者

---

由 Cameron Rye 用 ❤️ 制作