# OpenZIM MCP Server

> Knowledge that works offline. OpenZIM MCP is a Model Context Protocol server that gives any
> AI model structured, secure access to ZIM archives — Wikipedia, Wiktionary, MedlinePlus, the
> Stack Exchange dumps — with no internet connection. Retrieval only: it reads local archives
> and never writes to them.

- Version: 3.3.4
- Released: 2026-09-18 (the release this documentation describes; not a per-page edit date)
- License: MIT
- Python: 3.12+
- Repository: https://github.com/cameronrye/openzim-mcp
- Documentation: https://cameronrye.github.io/openzim-mcp/
- PyPI: https://pypi.org/project/openzim-mcp/

Every page below is also served as plain Markdown without the site shell, at
`https://cameronrye.github.io/openzim-mcp/docs/<slug>.md`. The whole corpus in one file: https://cameronrye.github.io/openzim-mcp/llms-full.txt

## Documentation

### Get started

- [Introduction](https://cameronrye.github.io/openzim-mcp/docs/): OpenZIM MCP is a secure, high-performance MCP server giving AI models offline access to ZIM-format knowledge bases via 8 consolidated tools.
- [Installation](https://cameronrye.github.io/openzim-mcp/docs/installation/): Install OpenZIM MCP from PyPI (uv or pip), Docker, or source on Windows, macOS, or Linux, then wire it into Claude Desktop or any MCP client.
- [Quick start](https://cameronrye.github.io/openzim-mcp/docs/quick-start/): Run OpenZIM MCP in 5 minutes — start the server in simple mode, dispatch a zim_query, and try one advanced-mode zim_search example.
- [ZIM concepts](https://cameronrye.github.io/openzim-mcp/docs/zim-concepts/): The four ideas the rest of the docs assume — sealed archives, the two namespace schemes, entry paths as archive-relative identifiers, and archive identity.
- [LLM integration patterns](https://cameronrye.github.io/openzim-mcp/docs/llm-integration-patterns/): Patterns for wiring OpenZIM MCP into LLM apps — simple-mode dispatch, advanced-mode 8-tool composition, progressive discovery, batching and error handling
- [Worked examples](https://cameronrye.github.io/openzim-mcp/docs/worked-examples/): Five end-to-end case studies of the advanced 8-tool surface — search, get, summarize, browse namespaces and follow related links in a Wikipedia archive.

### Concepts

- [Smart retrieval](https://cameronrye.github.io/openzim-mcp/docs/smart-retrieval/): How OpenZIM MCP resolves entry paths when direct access fails — the five-step fallback inside zim_get, the path-mapping cache, and how to debug resolutions.
- [Search reranking](https://cameronrye.github.io/openzim-mcp/docs/search-reranking/): The optional [reranker] extra — cross-encoder relevance reranking over Xapian's BM25 results, the mandatory model-staging step, and the knobs that turn it off.
- [Architecture overview](https://cameronrye.github.io/openzim-mcp/docs/architecture-overview/): Module map, transports and the zim/ package layout — the 8-tool surface, caching, smart-retrieval fallback, MCP transport layer, and the subscription watcher.

### Reference

- [API reference](https://cameronrye.github.io/openzim-mcp/docs/api-reference/): Every tool, prompt, and resource — 8 consolidated advanced tools, 3 slash-command prompts, 1 resource and 2 URI templates, plus the v1 → v2 migration table.
- [Configuration](https://cameronrye.github.io/openzim-mcp/docs/configuration/): Every supported environment variable, CLI flag and configuration field — transport, cache, content, rate limiting, subscriptions, and deployment profiles.
- [Resources, prompts & subscriptions](https://cameronrye.github.io/openzim-mcp/docs/resources-prompts-subscriptions/): MCP resources (zim://files, zim://{name}, zim://{name}/entry/{path}), the /research, /summarize and /explore slash-command prompts, and polling subscriptions.
- [CLI reference](https://cameronrye.github.io/openzim-mcp/docs/cli-reference/): Every openzim-mcp command and flag — the server invocation, the link-graph sidecar builder, and the model pre-staging command, with their exit-code contracts.

### Operate

- [HTTP and Docker deployment](https://cameronrye.github.io/openzim-mcp/docs/http-and-docker-deployment/): Run OpenZIM MCP as a networked service — streamable HTTP transport, bearer-token auth, CORS, health probes, the Docker image and LAN, Tailscale and TLS recipes
- [Performance optimization](https://cameronrye.github.io/openzim-mcp/docs/performance-optimization/): Cache tuning, rate limiting, batching, and symptom-to-knob guidance for OpenZIM MCP — including HTTP transport, monitoring endpoints, and latency targets.
- [Security best practices](https://cameronrye.github.io/openzim-mcp/docs/security-best-practices/): Security model and operator hardening — path validation, redaction, input sanitization, bearer-token auth, CORS, rate limits and a production checklist
- [Troubleshooting](https://cameronrye.github.io/openzim-mcp/docs/troubleshooting/): Common failure modes — installation, ZIM file access, client config, search and content issues, HTTP transport, cache, subscriptions and the error envelope
- [FAQ](https://cameronrye.github.io/openzim-mcp/docs/faq/): Common questions — v1 → v2 migration, simple vs advanced mode, the 8-tool context-tax win, ZIM files, configuration, security and where to get help
- [Upgrading](https://cameronrye.github.io/openzim-mcp/docs/upgrading/): What breaks between major versions and what to do about it — v2 to v3 for subscription clients and link-graph sidecars, plus a pointer to the v1 to v2 mapping.

## Installation

```bash
uv tool install openzim-mcp     # isolated CLI install (recommended)
pip install openzim-mcp         # or into the current environment
```

Get one real archive to try it against (13.6 MB):

```bash
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
```

## Quick start

```bash
openzim-mcp ~/zim-files                              # simple mode (the default): zim_query only
openzim-mcp --mode advanced ~/zim-files              # all 8 tools
openzim-mcp --transport http --host 127.0.0.1 --port 8000 ~/zim-files
openzim-mcp --version
```

The server takes **directories**, not individual files. The published Docker image sets
`OPENZIM_MCP_TOOL_MODE=advanced`, so a container registers the full surface with no flag.

## MCP configuration

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

## Core concepts

**ZIM format.** An open format for storing web content offline: Zstandard compression, fast
random access, a built-in full-text index, and namespace organisation. An archive is **sealed** —
its content cannot change without replacing the file, which is why responses cache safely.

**Namespaces.** Two schemes are in circulation. New-scheme archives put all content under `C`,
metadata under `M`, well-known entries under `W`, and search indexes under `X`. Old-scheme
archives spread content across `A` (articles), `I` (images) and `-` (layout). You cannot tell
which an archive uses without asking it, so prefer search or `zim_query` over guessing a path.

**Entry paths** are archive-relative identifiers (`C/Climate_change`, `A/Climate_change`), never
URLs. Passed as *tool arguments* they are plain UTF-8 — do not URL-encode them. The one exception
is the entry **resource** template, where `/` inside `{path}` must be percent-encoded as `%2F`.

**Smart retrieval.** When an exact entry lookup misses, `zim_get` walks a five-step ladder —
encoding variants, namespace probes, `M/<key>` routing, alternate-spelling exact probes, then
search — and caches the mapping it finds. No manual retry is needed.

## Available tools

Simple mode (the default) registers **`zim_query` alone**; advanced mode registers all 8.
There is no health or configuration intent in simple mode — asking `zim_query` about server
health searches the *archive* for that phrase.

- `zim_query`: Natural-language entry point, and the only tool simple mode registers. Parses the request, picks the operation, and renders the result. `synthesize=True` runs a multi-archive search/fusion/citation pipeline.
- `zim_search`: Full-text / title / suggest search. `mode="fulltext" | "title" | "suggest"`; `cross_file=True` fans out serially across archives under an aggregate time budget.
- `zim_get`: Single / batch / binary / main-page entry fetch. Branches: `entry_path` (single), `entry_paths` (batch), `main_page=True`, `binary=True`, `view="summary" | "toc" | "structure"`. The single-entry branch returns a dict, not rendered markdown.
- `zim_get_section`: Section-level fetch by section id, with `include_subsections`.
- `zim_browse`: Namespace listing. `mode="page"` is a sampled overview (limit 1-200); `mode="walk"` is deterministic cursor-paginated iteration (limit 1-500).
- `zim_metadata`: Archive metadata plus namespace inventory. Metadata keys are capitalised as libzim emits them: `Title`, `Language`, `Creator`, `Publisher`, `Date`, `Flavour`.
- `zim_links`: Outbound / inbound / related links. `direction="inbound"` ("what links here") needs the sidecar built by `openzim-mcp build link-graph <archive>.zim`; v3.0.0 invalidated 2.x sidecars.
- `zim_health`: Server health, resolved configuration, and loaded archives in one call. Advanced mode only.

## MCP prompts

- `/research <topic>`: Search across all archives, then drill into top hits
- `/summarize <zim_file_path> <entry_path>`: TOC + summary + key links
- `/explore <zim_file_path>`: High-level briefing of one archive

## MCP resources

- `zim://files`: index of every available ZIM file; each row carries `readable`
- `zim://{name}`: overview of one archive (metadata, namespaces, main-page preview)
- `zim://{name}/entry/{path}`: one entry with its native MIME type. Percent-encode `/` in
  `{path}` as `%2F` — e.g. `zim://wikipedia_en/entry/C%2FClimate_change`

## Common use cases

```python
# Ask a question without knowing the path
zim_query(query="what caused the French Revolution")

# Search, then read
zim_search(query="quantum physics", zim_file_path="wikipedia_en.zim", limit=10)
zim_get(zim_file_path="wikipedia_en.zim", entry_path="C/Quantum_mechanics")

# Discover neighbours
zim_links(zim_file_path="wikipedia_en.zim", entry_path="C/Quantum_mechanics", direction="related")

# Front page, autocomplete, inventory, deterministic iteration
zim_get(zim_file_path="wikipedia_en.zim", main_page=True)
zim_search(query="artif", zim_file_path="wikipedia_en.zim", mode="suggest")
zim_metadata(zim_file_path="wikipedia_en.zim")
zim_browse(zim_file_path="wikipedia_en.zim", namespace="C", mode="walk", limit=200)
```

## Error handling

- Failures are **returned, not raised**: `{"error": true, "operation": "<op>", "message": "<text>"}`
- The `CallToolResult` also carries `isError: true` for these envelopes
- `context` appears only when the tool supplies one; some failures merge self-correction keys
  (`zim_get_section` adds `available_section_ids` and `closest_match`; `unknown_argument` adds
  `accepted_arguments` and `closest_matches`)
- There is no `status` key and no `hint` key — branch on `result["error"] is True`
- No tool advertises an `outputSchema`, so nothing arrives in `structuredContent`; parse the
  JSON text block in `content`
- Enum values typed `Literal` are rejected by pydantic before the tool body runs, so they come
  back as `operation="invalid_argument"` with an `invalid_arguments` key. `zim_browse.mode` is
  the one enum that answers under its own name, `invalid_mode`
- Partial failures do **not** flag the call: a `zim_get(entry_paths=[...])` batch or a
  `zim_search(cross_file=True)` fan-out where some rows fail still returns `isError: false`.
  Batch rows carry `success` plus an `error` message string; cross-archive rows carry `error`
  (bool) plus `error_message` / `error_operation`

## Configuration

Environment variables, `OPENZIM_MCP_` prefixed, `__` for nesting:

```bash
export OPENZIM_MCP_TOOL_MODE=advanced          # default simple
export OPENZIM_MCP_TRANSPORT=http              # default stdio
export OPENZIM_MCP_AUTH_TOKEN="…"              # non-loopback HTTP refuses to start without it
export OPENZIM_MCP_CACHE__MAX_SIZE=1000        # default 100
export OPENZIM_MCP_CACHE__TTL_SECONDS=14400    # default 3600
export OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH=200000  # default 100000
export OPENZIM_MCP_LOGGING__LEVEL=INFO
```

Full reference: https://cameronrye.github.io/openzim-mcp/docs/configuration/

## Links

- Documentation: https://cameronrye.github.io/openzim-mcp/
- Source: https://github.com/cameronrye/openzim-mcp
- Changelog: https://github.com/cameronrye/openzim-mcp/blob/main/CHANGELOG.md
- PyPI: https://pypi.org/project/openzim-mcp/
- ZIM format specification: https://openzim.org/wiki/ZIM_file_format
- ZIM archive library: https://browse.library.kiwix.org/
- openZIM project: https://openzim.org/