Introduction

OpenZIM MCP is a modern, secure, and high-performance MCP (Model Context Protocol) server that enables AI models to access and search ZIM format knowledge bases offline.

8-tool advanced surface. A lean advanced surface of 8 composable tools — zim_query, zim_search, zim_get, zim_get_section, zim_browse, zim_metadata, zim_links, zim_health — keeps the advanced-mode wire footprint near ~23.5KB (down from ~36KB across 22 tools), clearing the MCP Tax pain band (25–50KB schema) for small-model dispatch. Simple mode (zim_query only) gives natural-language clients a single tool. Also built in: archive-type presets that auto-tune retrieval per source (Wikipedia, Stack Exchange, …), inbound link discovery (“what links here”), and native libzim health/introspection via zim_health(zim_file_path=...) + zim_metadata. Changelog →

Still running v1.x? Highlights for v1.2.0 and v1.0.0 remain documented in the changelog. The v1.x maintenance window closed when v2.5.0 shipped (2026-06-18); the 2.x line is now the only supported series. The ghcr.io/cameronrye/openzim-mcp:1.2.0 image stays available, but receives no further fixes.

What Makes OpenZIM MCP Different

Built for LLM Intelligence

OpenZIM MCP provides intelligent, structured access that LLMs need:

  • Dual-mode surface — Simple mode (default) exposes a single natural-language tool (zim_query) for smaller LLMs; Advanced mode exposes the 8 specialized tools for hosts that can pick from a richer surface.
  • Smart navigation — browse by namespace (articles, metadata, media) instead of blind searching. zim_browse(mode="walk") does deterministic cursor-paginated iteration.
  • Multi-archive search — zim_search(cross_file=True) queries every ZIM file at once; zim_search(mode="title") resolves titles directly without full-text scoring.
  • Smart retrieval — automatic fallback from direct path access to search-derived term resolution, with archive-scoped path-mapping cache and bounded redirect-chain following.
  • Batch retrieval — zim_get(entry_paths=[...]) fetches up to 50 entries in one call with per-entry success/error reporting.
  • MCP prompts — pre-built workflows (/research, /summarize, /explore) orchestrate multi-step ZIM operations.
  • MCP resources — zim://files, zim://{name}, zim://{name}/entry/{path} integrate with MCP-aware client browsers and @-mention pickers; subscribe for live update notifications.
  • Binary content — zim_get(binary=True) extracts PDFs, images, and other embedded media for multi-agent workflows.

Operations & Security

  • Streamable HTTP transport with bearer-token auth, CORS allow-list, and /healthz / /readyz probes.
  • Safe-default startup check refuses to bind a non-localhost host without an auth token.
  • Path and PID redaction in error responses and diagnostics — rejected traversals no longer leak the canonical allowed-directory layout.
  • Atomic rate limiting — global + per-operation token-bucket acquire is single-pass; no transient over-consumption.
  • Multi-arch Docker image — ghcr.io/cameronrye/openzim-mcp, builds for linux/amd64 and linux/arm64, runs as non-root, and defaults to stdio (HTTP is an explicit opt-in).

Use Cases

  • Research & knowledge management — offline Wikipedia / Wiktionary / academic archives behind an MCP-aware assistant.
  • Knowledge chatbots — give a small/local LLM real reference material instead of relying on weights.
  • Compliance / air-gapped environments — offline knowledge access without internet egress.
  • Multi-agent workflows — extract binary entries (PDFs, images) and pass to specialized processors.

Project Status

  • Version: 2.5.1
  • License: MIT
  • Python: 3.12+
  • Test Coverage: 80%+
  • Container: ghcr.io/cameronrye/openzim-mcp:2.5.1 + :latest (linux/amd64, linux/arm64)

Need help? Start with the Quick start; for HTTP/Docker deployment see HTTP and Docker Deployment; for failure modes see Troubleshooting.

Edit this page on GitHub ↗