OpenZIM MCP Server

Transform static ZIM archives into dynamic knowledge engines for AI models

🆕 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 via zim_health(zim_file_path=...), plus archive identity / index introspection in zim_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.

Smithery & one-click install

OpenZIM MCP is listed on the Smithery registry. Add it to your MCP client with the Smithery CLI:

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

For a one-click Claude Desktop extension, download the openzim-mcp-<version>.mcpb asset (and its .sha256) from the latest release and double-click it. The bundle launches the version-pinned uvx openzim-mcp@<version> (so the host needs uv) and prompts for your ZIM directory. Maintainer runbook: docs/distribution.md.

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 receive notifications/resources/updated when 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), and zim_metadata now reports archive identity, full-text / title index capabilities, and an M/Counter mimetype 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.sqlite next 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/.

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.

Security

See SECURITY.md for the vulnerability disclosure policy. No known CVEs.