{ "markdown": "

\n \"OpenZIM\n

\n\n

OpenZIM MCP Server

\n\n

\n Transform static ZIM archives into dynamic knowledge engines for AI models\n

\n\n

\n \"CI\"\n \"codecov\"\n \"CodeQL\"\n \"Security\n

\n\n

\n \"PyPI\n \"PyPI\n \"PyPI\n \"License:\n

\n\n

\n \n \"OpenZIM\n \n

\n\n---\n\n> ✨ **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](https://smithery.ai/servers/rye/openzim-mcp) and the [official MCP Registry](https://registry.modelcontextprotocol.io). [Release notes →](CHANGELOG.md) [Docs →](https://cameronrye.github.io/openzim-mcp/docs/)\n\n**OpenZIM MCP** is a modern, secure, high-performance [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI models structured, offline access to [ZIM format](https://en.wikipedia.org/wiki/ZIM_(file_format)) knowledge archives — Wikipedia, Wiktionary, Stack Exchange, and the rest of the [Kiwix Library](https://browse.library.kiwix.org/).\n\nBuilt 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.\n\nStreamable HTTP transport, per-entry MCP resources with live change notifications, and dual Simple / Advanced modes are all built in.\n\n## Install\n\n```bash\n# uv (recommended — isolated CLI tool)\nuv tool install openzim-mcp\n\n# pip\npip install openzim-mcp\n\n# Docker (multi-arch image, ghcr.io) — runs as a local stdio MCP server\ndocker pull ghcr.io/cameronrye/openzim-mcp\ndocker run -i --rm -v ~/zim-files:/data ghcr.io/cameronrye/openzim-mcp\n```\n\nThe 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](#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](https://cameronrye.github.io/openzim-mcp/docs/http-and-docker-deployment/).\n\nVerify the install:\n\n```bash\nopenzim-mcp --help\n```\n\n### Get your first ZIM archive\n\nThe 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:\n\n```bash\nmkdir -p ~/zim-files\ncurl -fsSL -o ~/zim-files/wikipedia_en_climate_change_mini_2024-06.zim \\\n https://raw.githubusercontent.com/openzim/zim-testing-suite/main/data/withns/wikipedia_en_climate_change_mini_2024-06.zim\n```\n\n`~/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](https://browse.library.kiwix.org/) and save the `.zim` into the same directory. More detail, including checksums and a Windows PowerShell equivalent: [Quick start](https://cameronrye.github.io/openzim-mcp/docs/quick-start/).\n\n### Smithery & one-click install\n\nOpenZIM MCP is listed on the [Smithery registry](https://smithery.ai/servers/rye/openzim-mcp) and the [official MCP Registry](https://registry.modelcontextprotocol.io) (as `io.github.cameronrye/openzim-mcp`). Add it to your MCP client with the Smithery CLI:\n\n```bash\nnpx @smithery/cli mcp add rye/openzim-mcp --client claude\n```\n\nFor a one-click **Claude Desktop extension**, download the `openzim-mcp-.mcpb` asset (and its `.sha256`) from the [latest release](https://github.com/cameronrye/openzim-mcp/releases/latest) and double-click it. The bundle launches the version-pinned `uvx openzim-mcp@` (so the host needs [uv](https://docs.astral.sh/uv/)) and prompts for your ZIM directory. Maintainer runbook: [docs/distribution.md](docs/distribution.md).\n\n\n\n## Quick start\n\nRun the server in Simple mode (default — exposes one natural-language tool, `zim_query`):\n\n```bash\nopenzim-mcp ~/zim-files\n```\n\nWire it into your MCP client. Example for Claude Desktop's `claude_desktop_config.json` (any MCP client that speaks stdio works the same way):\n\n```json\n{\n \"mcpServers\": {\n \"openzim-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"openzim-mcp\", \"~/zim-files\"]\n }\n }\n}\n```\n\nOnce the client connects, ask your LLM: *\"summarize the article on Photosynthesis\"* — `zim_query` dispatches to the right underlying tool automatically.\n\nFor full control, run in Advanced mode to expose all 8 specialized tools:\n\n```json\n{\n \"mcpServers\": {\n \"openzim-mcp-advanced\": {\n \"command\": \"uvx\",\n \"args\": [\"openzim-mcp\", \"--mode\", \"advanced\", \"~/zim-files\"]\n }\n }\n}\n```\n\nFor HTTP transport (long-running service with bearer auth, CORS, and health endpoints) see [HTTP & Docker deployment](https://cameronrye.github.io/openzim-mcp/docs/http-and-docker-deployment/).\n\n## Highlights\n\n- **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](https://www.mmntm.net/articles/mcp-context-tax) pain band. [API reference →](https://cameronrye.github.io/openzim-mcp/docs/api-reference/)\n- **Streamable HTTP transport** — bearer-token auth, CORS, health endpoints, multi-arch Docker image. [HTTP & Docker deployment →](https://cameronrye.github.io/openzim-mcp/docs/http-and-docker-deployment/)\n- **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 →](https://cameronrye.github.io/openzim-mcp/docs/resources-prompts-subscriptions/)\n- **Simple-mode `zim_query`** — one natural-language tool that dispatches to the right operation, tuned for small-model deployment targets. [Quick start →](https://cameronrye.github.io/openzim-mcp/docs/quick-start/)\n- **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`).\n- **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 →](https://cameronrye.github.io/openzim-mcp/docs/api-reference/)\n- **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 .zim` (writes `.zim.linkgraph.sqlite` next to the archive). [API reference →](https://cameronrye.github.io/openzim-mcp/docs/api-reference/)\n\n## Modes\n\nOpenZIM MCP ships two modes; pick one per client.\n\n**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.\n\n**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.\n\nRule 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](https://cameronrye.github.io/openzim-mcp/docs/llm-integration-patterns/) for guidance on choosing.\n\n## Documentation\n\nFull documentation lives at ****.\n\n| Group | Pages |\n| --- | --- |\n| [Get started](https://cameronrye.github.io/openzim-mcp/docs/) | Introduction · Installation · Quick start · ZIM concepts · LLM integration patterns · Worked examples |\n| [Concepts](https://cameronrye.github.io/openzim-mcp/docs/smart-retrieval/) | Smart retrieval · Search reranking · Architecture overview |\n| [Reference](https://cameronrye.github.io/openzim-mcp/docs/api-reference/) | API reference · Configuration · Resources, prompts & subscriptions · CLI reference |\n| [Operate](https://cameronrye.github.io/openzim-mcp/docs/http-and-docker-deployment/) | HTTP and Docker deployment · Performance optimization · Security best practices · Troubleshooting · FAQ · Upgrading |\n\n## Project status\n\n**v3.3.3** is the current release (2026-09-11). \nv2.0.0 GA shipped 2026-05-27. Per [SECURITY.md](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](CHANGELOG.md), and step-by-step instructions in the [upgrade guide](https://cameronrye.github.io/openzim-mcp/docs/upgrading/).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test commands, code style, and the release process.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the vulnerability disclosure policy. No known CVEs.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Acknowledgments\n\n- [openZIM](https://openzim.org/) and [Kiwix](https://www.kiwix.org/) for the ZIM format and libzim library\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the open client-server protocol\n- The open-source community and contributors\n\n---\n\nMade with ❤️ by [Cameron Rye](https://rye.dev)\n", "bytes": 13038, "sha": "c3e96064b1f6b5ce4534659ff0e177545f3f2d1f8dcc68c44b0a131e252a3416", "repo_slug": "cameronrye/openzim-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_cameronrye_openzim_mcp_d3165057/readme" }