openzim-mcp

✨ Highlights. A lean 8-tool advanced surface (zim_query, zim_search, zim_get, zim_get_section, zim_browse, zim_metadata, zim_links, zim_health) with a schema small enough for small-model dispatch — or one-tool Simple mode for natural-language queries. Archive-type presets auto-tune retrieval per source (Wikipedia, Stack Exchange, …), inbound link discovery answers "what links here," and native libzim introspection validates and inspects any archive. Available on Smithery and the official MCP Registry. 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 live change notifications, and dual Simple / Advanced modes are all built in.

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 ~/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

Get your first ZIM archive

The server does nothing without an archive to read. Grab a real one — a 13.6 MB extract of English Wikipedia on climate change, from the openZIM project's own testing suite. No account, nothing to install:

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 is the directory every example below points the server at — the server expands ~ itself, so it works from a shell and from a client config file alike. For full archives — Wikipedia, Wiktionary, Stack Exchange and the rest, ranging from a few hundred MB to tens of GB — browse browse.library.kiwix.org and save the .zim into the same directory. More detail, including checksums and a Windows PowerShell equivalent: Quick start.

Smithery & one-click install

OpenZIM MCP is listed on the Smithery registry and the official MCP Registry (as io.github.cameronrye/openzim-mcp). 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 ~/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": "uvx",
      "args": ["openzim-mcp", "~/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": "uvx",
      "args": ["openzim-mcp", "--mode", "advanced", "~/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 ~24.1KB, 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 open a subscriptions/listen stream and get resources/list_changed when a ZIM appears or disappears, resources/updated when one is replaced. 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 →
• Archive-type presets — OpenZIM MCP detects the archive type (Wikipedia, Stack Exchange, and more) and auto-tunes retrieval and summarization for it — e.g. Stack Exchange dumps render as clean Q&A instead of vote-score noise. Operators can override the bundled defaults with a TOML file (OPENZIM_MCP_PRESETS_OVERRIDE_PATH).
• Native libzim introspection — zim_health(zim_file_path=...) validates an archive's integrity (Archive.check() + checksum), and zim_metadata 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 th