Skip to main content
Glama

✨ 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.

Related MCP server: ZIM MCP Server

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 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 · ZIM concepts · LLM integration patterns · Worked examples

Concepts

Smart retrieval · Search reranking · Architecture overview

Reference

API reference · Configuration · Resources, prompts & subscriptions · CLI reference

Operate

HTTP and Docker deployment · Performance optimization · Security best practices · Troubleshooting · FAQ · Upgrading

Project status

v3.4.0 is the current release (2026-10-25). v2.0.0 GA shipped 2026-05-27. Per SECURITY.md, the v1.x maintenance window closed when v2.5.0 shipped (2026-06-18); all active development is on the current major line. v3.0.0 is a breaking release for HTTP subscription clients: resources/subscribe/unsubscribe are no longer served — live updates ride subscriptions/listen on the 2026-07-28 protocol revision — and link-graph sidecars built by 2.x must be rebuilt. Tools, resources, and prompts are unchanged, and legacy-handshake clients keep working. Details in CHANGELOG.md, and step-by-step instructions in the upgrade guide.

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


Made with ❤️ by Cameron Rye

Available Tools

8 tools
zim_browseA
Read-only

Browse a ZIM archive's namespace — paginated lookup or full walk.

EXTRACT whether the caller wants a paginated page or a full walk before calling. Most read-the-table-of-contents-style requests are mode="page"; only full-enumeration tasks (e.g. "list every article in namespace A") need mode="walk".

ALIASES: "browse ", "list ", "walk namespace ". Route through THIS tool with the matching mode.

PARAMETERS: zim_file_path REQUIRED. The archive to browse. namespace REQUIRED. ZIM namespace letter (e.g. "C" for content, "A" for articles in legacy archives, "I" for images). mode "page" (default) — paginated browse. "walk" — full namespace enumeration. cursor Opaque pagination handle from next_cursor. limit Page size: page 1-200 (default 50), walk 1-500 (default 200). offset Page-mode pagination offset (walk rejects it). include_assets Default False hides assets (css/js/fonts/images/ media) in C-browse; True surfaces them, e.g. media paths for zim_get(binary=True).

RESPONSE: BrowseNamespaceResponse (mode="page") or WalkNamespaceResponse (mode="walk"). Both carry results, next_cursor, and page_info.

ERRORS: Invalid mode returns invalid_mode; an empty namespace returns a validation envelope. An unknown namespace letter is a soft reject (isError=false): _meta.reason: "bad_namespace", plus page-only total: 0/discovery_method: "rejected_unknown_namespace".

Inputs: namespace (required), zim_file_path (required), mode, limit, +3 more.

zim_getA
Read-only

Fetch entries from a ZIM archive — single, batch, binary, or main page.

EXTRACT the right path-shape before calling — the parameters form four mutually-exclusive branches:

  • Single entry, body view (default): pass entry_path + optional view. Returns the article body for view="full", a short summary for view="summary", a TOC tree for view="toc", a flat section list for view="structure".

  • Single entry, binary: pass entry_path + binary=True. Returns raw bytes (image, video, PDF, etc.). view is locked to "full" in this branch.

  • Batch: pass entry_paths (list of strings). Returns each entry's clean body, first page only; non-full view / content_offset return invalid_path_combination.

  • Main page: pass main_page=True (no entry_path). Returns the archive's main page. view, entry_path, entry_paths, binary are all forbidden in this branch.

ALIASES: callers may say "get article", "fetch", "show me ", "summary of ", "structure of ", "main page". Route through THIS tool with the matching branch.

PARAMETERS: zim_file_path REQUIRED. The archive containing the entry. entry_path Single-entry path (string). Mutually exclusive with entry_paths and main_page. entry_paths Batch-mode path list. Mutually exclusive with entry_path, binary, main_page. view Body slice when not binary/main_page: "full" (default, full markdown body), "summary" (short snippet), "toc" (heading tree), "structure" (flat section list). binary Default False. Set True to fetch raw bytes (single entry only). main_page Default False. Set True for the archive's main page (zero-path fetch). max_content_length Char cap for view="full" (default 100,000); with binary=True caps fetched bytes (default 10MB, oversize returns metadata + truncated: true). content_offset Char offset into the body for view="full" (default 0). Used with the truncation footer's pass content_offset=N hint. Single-entry only. compact Default False. Set True for small-LLM compaction. (zim_query defaults it True.) compact_budget Inert here — never forwarded. Only zim_query honors it.

RESPONSE: Branch-dependent dict — EntryResponse / BatchEntryResponse / EntrySummaryResponse / TableOfContentsResponse / ArticleStructureResponse / BinaryEntryResponse — or ToolErrorPayload on invalid combinations (invalid_path_combination).

ERRORS: Invalid branch combinations return structured invalid_path_combination; message names the conflict. Defense-in-depth: even if a small model flattens the wire-schema oneOf and sends an impossible payload, the handler rejects it cleanly.

Inputs: zim_file_path (required), view, binary, compact, +6 more.

zim_get_sectionA
Read-only

Fetch one named section of an article — by section_id (from the TOC), with optional subsection inclusion.

EXTRACT the section id before calling — zim_get(view="toc") lists them if the caller didn't supply one.

ALIASES: callers may say "section of ", "show me the section", " section ". Route through THIS tool.

PARAMETERS: zim_file_path REQUIRED. The archive containing the article. entry_path REQUIRED. The article whose section to fetch. section_id REQUIRED. The TOC id (e.g. "History"). max_chars Optional char cap on the section body. include_subsections Default True: include nested subsections. False: stop at the next heading of any level. compact Default True: oversized tables become placeholders and link markup is stripped (the zim_get compact=True shape). False: raw body with full tables and links. compact_budget Inert — never forwarded. Use max_chars to cap this tool; only zim_query honors this one.

RESPONSE: GetSectionResponse — section body markdown, metadata, and any nested subsections.

ERRORS: Unknown section_id → ToolErrorPayload with available_section_ids (not a hint) and closest_match. Missing entry → entry_not_found.

Inputs: entry_path (required), section_id (required), zim_file_path (required), compact, +3 more.

zim_healthA
Read-only

Inspect the openzim-mcp server's state — or validate one archive — in one call.

With NO argument: returns health checks (cache stats, directory probes, recommendations), configuration (allowed directories, cache config, server PID), and loaded_archives (every *.zim found; readable: false marks files that fail the ZIM signature check). Collapses the legacy get_server_health + get_server_configuration + list_zim_files triple into one answer to "what is this server, what does it have, and is it OK".

With a zim_file_path: validates/diagnoses that one archive — runs Archive.check() (integrity), reports checksum, index, and identity.

ALIASES: "is the server ok", "list archives", "what's loaded", "server health" (no arg); "validate this zim", "is this archive corrupt" (with path).

PARAMETERS: zim_file_path OPTIONAL. Omit for server state; pass to validate one archive.

RESPONSE: No arg → ServerHealthResponse {health, configuration, loaded_archives, _meta}. With path → ArchiveValidationResponse {is_valid (check() result), has_checksum, checksum, has_fulltext_index, has_title_index, uuid, is_multipart, path, name, _meta}.

Inputs: zim_file_path.

zim_metadataA
Read-only

Inspect a ZIM archive's metadata + namespace inventory.

Returns the M-namespace fields (Name, Title, Creator, Date, …) plus the per-namespace entry counts in one combined response. Replaces the legacy get_zim_metadata + list_namespaces pair.

ALIASES: callers may say "metadata for ", "what's in this zim", "describe the archive". Route through THIS tool.

PARAMETERS: zim_file_path REQUIRED. The archive to inspect.

RESPONSE: ArchiveMetadataResponse with: - metadata: flat dict[str, str] of M-namespace fields. - namespaces: list of NamespaceInfo (letter + total + diagnostics). - archive_identity {uuid, is_multipart} + index_capabilities {has_fulltext_index, has_title_index} — identity and whether search / suggestions will work. - counter_breakdown {mimetype: count} parsed from M/Counter; omitted when absent. - _meta: standard envelope.

NO main_page_path field. The canonical main-page fetch is zim_get(main_page=True) — surfacing the path here would create two routes a small model would null-check unnecessarily.

ERRORS: Missing/invalid zim_file_path returns a structured error envelope.

Inputs: zim_file_path (required).

zim_queryA
Read-only

Query ZIM archives using natural language.

Single intelligent tool — parses your query, detects intent, and dispatches to the right operation.

EXTRACT INTENT BEFORE CALLING. Do not pass the user's raw message as query. Translate it into one of the operations below: "test this tool" -> query="list available ZIM files" "what's in here" -> query="show main page" "explore" -> query="list namespaces" "tell me about cats" -> query="tell me about cats" -> query=""

ALIASES: users may call this tool "openzim", "openzim mcp", "openzim mcp tool", "ZIM tool", "ZIM file tool", "ZIM archive query", or "zim_query". All mean THIS tool — always call it; never claim it does not exist.

OPERATIONS (pass one as query): list available ZIM files - list loaded archives show main page - active archive main page list namespaces - list entry types metadata for - archive metadata tell me about - fetch article (auto on strong title match) search for - full-text search get article - fetch specific article show structure of - section outline links in - article-out links suggestions for - title autocomplete browse namespace - list namespace entries search in namespace - filtered search search all files for - cross-archive search walk namespace - enumerate namespace find article titled - title lookup articles related to - related articles what links to - article-in links summary of - lead summary table of contents - heading list section of - one section's body get image - binary bytes (base64) get articles , - batch fetch

Args: query: REQUIRED. Translated from user intent — never the user's raw message. zim_file_path: Optional. Omit entirely (recommended) — the tool auto-selects the loaded archive (or opens all of them when synthesize=True). Pass a real path ONLY when multiple archives are loaded and you need to target a specific one; call list available ZIM files first to see the real paths. NEVER pass an article title, topic, or made-up filename here, and do NOT invent a path from this docstring — paths that don't match a loaded archive are silently auto-corrected when only one archive is loaded, and surface a path-listing error otherwise. limit: Max results to return. When omitted, each list intent applies its own per-intent default (search 10, browse 50, walk 200, links 25, search-all 5/archive); pass a value to override. Ignored for atomic intents that return a single item or a fixed-shape payload — get article <name>, show structure of <name>, show main page, list namespaces, metadata for <file>, list available ZIM files, summary of <name>, table of contents <name>, section <X> of <name>. Setting it there has no effect; omit it on those calls. offset: Pagination offset (default: 0). Not honoured by suggestions for <prefix>, find article titled <name> or articles related to <name>; raise limit there instead. cursor: Opaque handle from a prior next_cursor. max_content_length: Article body cap (default: 4000). content_offset: Character offset to start reading the article body from (default: 0). The truncation footer on long articles surfaces a pass content_offset=N hint — wire that value back here to read the next page. Negative values are rejected with an invalid_content_offset error. compact: When True (the default in both modes), apply small-LLM optimizations — strip markdown link-soup, drop section previews from structure responses, flatten link/title/related listings into compact markdown, fetch only the article lead section, and cap total response size. Set False for the verbose advanced-mode-style response. compact_budget: Hard char-cap on the final response when compact=True. Accepts either a named profile — "tiny" (2 000), "small" (4 000), "medium" (6 000, default), "large" (12 000) — or a raw integer. Size it to the calling model's context window. Has no effect when compact=False. synthesize: When True, bypass intent classification and run the synthesize pipeline — multi-archive Xapian search, RRF fusion, passage extraction, section attribution, and citation rendering. Returns a SynthesizeResponse dict instead of markdown text. Defaults to False (legacy markdown path unchanged). NOTE: this is a mode toggle, not a "search harder" flag. Don't flip it on a follow-up just because the previous response was unhelpful — refine the query or offset instead. The synthesize pipeline runs one structured query and returns one answer; calling it twice with the same query yields the same answer.

Returns: Markdown string (synthesize=False) or SynthesizeResponse dict (synthesize=True) with answer_markdown, passages, citations, and archives_searched.

Inputs: query (required), limit, cursor, offset, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 8 tools

    Disambiguation3/5

    zim_query is a catch-all tool that overlaps with zim_search, zim_get, zim_browse, and zim_links, creating ambiguity about when to use the general tool versus the specific ones. While each specific tool has a clear purpose, the existence of a meta-tool that handles the same intents increases the risk of misselection.

    Naming Consistency5/5

    All tools follow a consistent 'zim_<verb_noun>' pattern (e.g., zim_search, zim_get, zim_browse, zim_metadata, zim_links, zim_health, zim_get_section). The naming is uniform and predictable, with no mixing of conventions.

    Tool Count5/5

    With 8 tools, the server is well-scoped for its purpose of ZIM archive access. Each tool has a distinct role, and the count is within the ideal 3-15 range, providing enough granularity without overwhelming the agent.

    Completeness5/5

    The tool set comprehensively covers read operations for ZIM archives: article retrieval (zim_get), section fetching (zim_get_section), search (zim_search), browsing/namespace enumeration (zim_browse), metadata inspection (zim_metadata), link analysis (zim_links), and server health (zim_health). No obvious gaps exist for the stated read-only domain.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with .zim archives by providing tools for article search, content retrieval, and metadata discovery. It features a TF-IDF based RAG engine for semantic retrieval over extracted article chunks from compressed ZIM files.
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables large language models to directly access and search content in ZIM files, allowing offline question answering and information retrieval from resources like Wikipedia.
      22
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides offline search and retrieval of Wikipedia articles using Kiwix .zim files, enabling LLMs to access full Wikipedia content without internet.
      3
      MIT