openzim

OpenZIM MCP Server turns static ZIM archives into dynamic knowledge engines tailored for AI models. It provides a Model Context Protocol (MCP) interface that lets LLMs browse and retrieve content from offline ZIM datasets with structured navigation, metadata access, and advanced search. The server supports two modes: Simple mode, which exposes a single intelligent tool for natural language queries over the ZIM content, and Advanced mode, which unlocks 18 specialized MCP tools for fine-grained control over queries, content extraction, and metadata navigation. Typical use cases include building offline QA assistants, knowledge bots, or research assistants that can query Wikipedia-like archives without requiring an internet connection. Start the server in your preferred mode and point it at the directory containing your ZIM files. The README provides concrete examples for both modes and demonstrates how to run the server from source or via installed packages.

To use the tools, choose either Simple Mode or Advanced Mode depending on your needs. In Simple Mode, you interact with a single zim_query-like tool that understands natural language queries and returns concise, relevant results. In Advanced Mode, you gain access to a suite of tools for nuanced tasks such as article retrieval, metadata inspection, media extraction, and structured content traversal. You can then integrate these MCP endpoints into your LLM-powered workflows, attach prompt templates, and configure caching and pagination as described in the project documentation. The server prioritizes secure input handling and efficient access to large ZIM files, enabling fast, offline knowledge retrieval for AI models.

Prerequisites:

• Python 3.8+ (recommended 3.10+)
• pip (comes with Python)
• Access to the ZIM files you want to index/use

Install OpenZIM MCP from PyPI:

pip install openzim-mcp

If you prefer running from source (development):

git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
# Optional: install development dependencies
pip install -e .[dev]

Prepare ZIM files:

mkdir -p /path/to/zim/files
# Download and place your ZIM files in /path/to/zim/files

Run the server (Simple/default mode):

python -m openzim_mcp /path/to/zim/files

Run the server (Advanced mode with all 18 tools):

python -m openzim_mcp --mode advanced /path/to/zim/files

If you are developing from source, you can also run via a package manager or using a Makefile target if provided by the project (e.g., make run ZIM_DIR=/path/to/zim/files).

Tips and notes:

• The server expects a directory of ZIM files. Ensure the path is accessible and contains valid ZIM archives.
• Simple Mode provides a single natural language querying tool; Advanced Mode exposes a comprehensive toolset for deeper control over retrieval, extraction, and navigation within ZIM content.
• Use the environment variable ZIM_DIR to point to your ZIM directory if you prefer not to pass the path as a positional argument.
• If you encounter performance issues with very large ZIM collections, enable caching and pagination options as described in the documentation; the MCP is designed to cache results to prevent timeouts.
• For development, you can run from source with uv or an equivalent runner as shown in the README, but when deploying, the PyPI installation is the simplest path.
• Common issues may include incorrect ZIM directory paths, missing permissions, or incompatible Python versions. Verify your Python version and ensure required dependencies are installed.