OpenZIM MCP Server
cameronrye/openzim-mcp
Acesso estruturado offline a arquivos ZIM para assistentes de IA
Ver no GitHubServidor MCP que transforma arquivos ZIM (Wikipedia offline, Kiwix) em bases de conhecimento acessíveis para modelos de IA. Oferece busca estruturada, navegação por namespace, extração de links e operações paginadas com validação robusta de segurança para acesso offline a repositórios de conhecimento massivos.
Instalação
npx convez-ai cameronrye/openzim-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Assistentes de pesquisa com Wikipedia/Kiwix offline
- Chatbots de conhecimento com busca full-text em grandes bases
- Análise de conteúdo e mapeamento de relações entre artigos
- Sistemas RAG offline com validação e cache inteligente
Veredito

Implementação madura (v2.1+) com 8 ferramentas consolidadas, validação nativa de libzim, cache e paginação. Ideal para quem precisa de conhecimento offline estruturado sem depender de APIs externas. Excelente cobertura de testes (CodeQL, SonarCloud, pytest) e documentação completa.
README
A tradução para o português deste README ainda está na fila.
🆕 8-tool advanced surface. Phase F (v2.0.0) consolidated 22 advanced tools into 8 (
zim_query,zim_search,zim_get,zim_get_section,zim_browse,zim_metadata,zim_links,zim_health). New in v2.1: native libzim archive validation viazim_health(zim_file_path=...), plus archive identity / index introspection inzim_metadata. Release notes → Docs →
OpenZIM MCP is a modern, secure, high-performance Model Context Protocol server that gives AI models structured, offline access to ZIM format knowledge archives — Wikipedia, Wiktionary, Stack Exchange, and the rest of the Kiwix Library.
Built for research assistants, knowledge chatbots, and content-analysis systems that need intelligent access to vast knowledge repositories — not just a raw text dump. Smart navigation by namespace (articles, metadata, media), structure-aware retrieval (sections, tables of contents, related articles), full-text search with suggestions and multi-archive search, and link-graph extraction to map content relationships. Cached, paginated operations keep things responsive across massive archives; comprehensive input validation and path-traversal protection keep things safe.
Streamable HTTP transport, per-entry MCP resources with subscriptions, and dual Simple / Advanced modes ship in v2.0.0.
Install
# 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 /path/to/zim/files:/data ghcr.io/cameronrye/openzim-mcp
The container defaults to stdio transport, so docker run -i speaks MCP over stdin/stdout — wire it into an MCP client the same way as the binary (see Quick start). For the long-running HTTP service (bearer auth, CORS, health endpoints), opt in at runtime with -e OPENZIM_MCP_TRANSPORT=http -e OPENZIM_MCP_HOST=0.0.0.0 -e OPENZIM_MCP_AUTH_TOKEN=… -p 8000:8000; see HTTP & Docker deployment.
Verify the install:
openzim-mcp --help
Download ZIM files from the Kiwix Library into a directory of your choice before running the server.
Quick start
Run the server in Simple mode (default — exposes one natural-language tool, zim_query):
openzim-mcp /path/to/zim/files
Wire it into your MCP client. Example for Claude Desktop's claude_desktop_config.json (any MCP client that speaks stdio works the same way):
{
"mcpServers": {
"openzim-mcp": {
"command": "openzim-mcp",
"args": ["/path/to/zim/files"]
}
}
}
Once the client connects, ask your LLM: "summarize the article on Photosynthesis" — zim_query dispatches to the right underlying tool automatically.
For full control, run in Advanced mode to expose all 8 specialized tools:
{
"mcpServers": {
"openzim-mcp-advanced": {
"command": "openzim-mcp",
"args": ["--mode", "advanced", "/path/to/zim/files"]
}
}
}
For HTTP transport (long-running service with bearer auth, CORS, and health endpoints) see HTTP & Docker deployment.
Highlights
- 8-tool advanced surface —
zim_query,zim_search,zim_get,zim_get_section,zim_browse,zim_metadata,zim_links,zim_health. Down from 22; advanced-mode schema drops from ~36KB to ~23.5KB, clearing the MCP Tax pain band. API reference → - Streamable HTTP transport — bearer-token auth, CORS, health endpoints, multi-arch Docker image. HTTP & Docker deployment →
- Per-entry MCP resources + subscriptions —
zim://{name}/entry/{path}with native MIME types; clients subscribe and receivenotifications/resources/updatedwhen archives change. Resources, prompts & subscriptions → - Simple-mode
zim_query— one natural-language tool that dispatches to the right operation, tuned for small-model deployment targets. Quick start → - Native libzim introspection (v2.1) —
zim_health(zim_file_path=...)validates an archive's integrity (Archive.check()+ checksum), andzim_metadatanow reports archive identity, full-text / title index capabilities, and anM/Countermimetype breakdown. API reference → - Inbound link discovery ("what links here") —
zim_links(direction="inbound")returns pages that link to an entry, ranked by linker importance. Requires a pre-built sidecar:openzim-mcp build link-graph <archive>.zim(writes<archive>.zim.linkgraph.sqlitenext to the archive). API reference →
Modes
OpenZIM MCP ships two modes; pick one per client.
Simple mode (default) exposes a single intelligent tool, zim_query, that parses natural-language requests and dispatches to the right underlying operation. Built for small-model deployment targets — the wire footprint is minimal and the dispatch happens server-side, not in the LLM context. Start here unless you have a specific reason not to.
Advanced mode exposes all 8 specialized tools (zim_query, zim_search, zim_get, zim_get_section, zim_browse, zim_metadata, zim_links, zim_health) plus 3 MCP prompts (/research, /summarize, /explore) and per-entry resources. Built for larger models that can reliably dispatch over the full schema, and for clients that want fine-grained control over pagination, namespace browsing, and link-graph extraction.
Rule of thumb: models ≤ 13B parameters benefit from Simple mode; larger models (Claude Sonnet/Opus, GPT-4o-class, Llama 70B+) can dispatch Advanced mode directly. See LLM integration patterns for guidance on choosing.
Documentation
Full documentation lives at https://cameronrye.github.io/openzim-mcp/docs/.
| Group | Pages |
|---|---|
| Get started | Introduction · Installation · Quick start |
| Reference | API reference · Configuration · Resources, prompts & subscriptions |
| Guides | LLM integration patterns · Smart retrieval · HTTP & Docker deployment · Performance optimization · Security best practices · Worked examples |
| Operations | Troubleshooting · FAQ · Architecture overview |
Project status
v2.0.0 GA shipped 2026-05-27. v1.x is in maintenance mode — security fixes, data-corruption fixes, and pre-v2.0.0 crash fixes accepted through 2026-11-27 or until v2.5.0 ships, whichever comes first. Full release history: CHANGELOG.md.
Contributing
See CONTRIBUTING.md for development setup, test commands, code style, and the release process.
Security
See SECURITY.md for the vulnerability disclosure policy. No known CVEs.
License
MIT. See LICENSE.
Acknowledgments
- openZIM and Kiwix for the ZIM format and libzim library
- Model Context Protocol for the open client-server protocol
- The open-source community and contributors
Made with ❤️ by Cameron Rye