OpenZIM MCP Logo

OpenZIM MCP Server

Transform static ZIM archives into dynamic knowledge engines for AI models

CI codecov CodeQL Security Rating

PyPI version PyPI - Python Version PyPI - Downloads License: MIT

OpenZIM MCP server quality badge

✨ 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 /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 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 /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": "uvx",
      "args": ["openzim-mcp", "/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": "uvx",
      "args": ["openzim-mcp", "--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.3KB, 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.2.4 is the current release (2026-08-31). 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

Project links

Data verified by PyPI on Aug 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cameronrye from gravatar.com cameronrye

Credits

Author/Maintainer: Cameron Rye

GitHub Statistics

Data verified by PyPI on Aug 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

reranker

Tags

zim openzim mcp model-context-protocol ai llm knowledge-base offline wikipedia search libzim

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openzim_mcp-3.2.4.tar.gz (1.4 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

openzim_mcp-3.2.4-py3-none-any.whl (637.3 kB view details)

Uploaded Python 3

File details

Details for the file openzim_mcp-3.2.4.tar.gz.

File metadata

  • Download URL: openzim_mcp-3.2.4.tar.gz
  • Upload date:
  • Size: 1.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openzim_mcp-3.2.4.tar.gz
Algorithm Hash digest
SHA256 98d7d7612dd37634b67a1c0dadfe83cd45f6fd72511e08a1c8be6c167c968975
MD5 02c7ac9f4a08d01583ac0b1ef826bc6e
BLAKE2b-256 a171fd8540932df90ed2b6e2da9488a947ae72d13438022d1b7572b5809d75a3

See more details on using hashes here.

Provenance

The following attestation bundles were made for openzim_mcp-3.2.4.tar.gz:

Publisher: release.yml on cameronrye/openzim-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openzim_mcp-3.2.4-py3-none-any.whl.

File metadata

  • Download URL: openzim_mcp-3.2.4-py3-none-any.whl
  • Upload date:
  • Size: 637.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openzim_mcp-3.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 6ddcee69a169576724c37f501771f98b3a2b5ffb0c951ec3f94fbdb8740ab17b
MD5 2d1cb9052d77bfcf663f6cfcc8c9086a
BLAKE2b-256 b9da55217c9889f285112307588b71e0d7ffd5e62b24985d855a7acceda03454

See more details on using hashes here.

Provenance

The following attestation bundles were made for openzim_mcp-3.2.4-py3-none-any.whl:

Publisher: release.yml on cameronrye/openzim-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

3.2.4 This release

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.0

2 files

2.7.0

2 files

2.6.5

2 files

2.6.4

2 files

2.6.3

2 files

2.6.1

2 files

2.6.0

2 files

2.5.5

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.5

2 files

2.4.4

2 files

2.4.3

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0

2 files

2.3.0

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.8

2 files

2.1.7

2 files

2.1.6

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

Pre-release

2.0.0rc1

2 files

Pre-release

2.0.0rc0

2 files

Pre-release

2.0.0b13

2 files

Pre-release

2.0.0b12

2 files

Pre-release

2.0.0b11

2 files

Pre-release

2.0.0b10

2 files

Pre-release

2.0.0b9

2 files

Pre-release

2.0.0b8

2 files

Pre-release

2.0.0b7

2 files

Pre-release

2.0.0b6

2 files

Pre-release

2.0.0b4

2 files

Pre-release

2.0.0b3

2 files

Pre-release

2.0.0b2

2 files

Pre-release

2.0.0b1

2 files

Pre-release

2.0.0a25

2 files

Pre-release

2.0.0a24

2 files

Pre-release

2.0.0a23

2 files

Pre-release

2.0.0a22

2 files

Pre-release

2.0.0a21

2 files

Pre-release

2.0.0a20

2 files

Pre-release

2.0.0a19

2 files

Pre-release

2.0.0a18

2 files

Pre-release

2.0.0a17

2 files

Pre-release

2.0.0a16

2 files

Pre-release

2.0.0a15

2 files

Pre-release

2.0.0a14

2 files

Pre-release

2.0.0a13

2 files

Pre-release

2.0.0a12

2 files

Pre-release

2.0.0a11

2 files

Pre-release

2.0.0a10

2 files

Pre-release

2.0.0a9

2 files

Pre-release

2.0.0a8

2 files

1.3.0

2 files

1.2.0

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.1

2 files

1.0.0

2 files

0.9.0

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.1

2 files

0.4.0

2 files

0.3.3

2 files

0.3.1

2 files

0.2.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page