Installation

This guide covers installing OpenZIM MCP on different platforms and for various use cases.

Prerequisites#

System Requirements#

Python: 3.12 or higher (3.13 also supported)
Operating System: Windows, macOS, or Linux
Memory: Minimum 512MB RAM (2GB+ recommended for large ZIM files)
Storage: Space for ZIM files (varies by content, typically 100MB - 50GB+)

Required Tools#

uv (recommended) or pip for package management. uv is the preferred installer for CLI tools because it creates an isolated, self-contained tool environment; pip is fine for venv-based installs.

Standard Installation (Recommended)#

Install from PyPI with uv (recommended)#

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install OpenZIM MCP as an isolated CLI tool
uv tool install openzim-mcp

# Verify installation
openzim-mcp --help

Install from PyPI with pip#

# Install OpenZIM MCP from PyPI
pip install openzim-mcp

# Verify installation
openzim-mcp --help

That’s it! OpenZIM MCP is now installed and ready to use.

Development Installation#

For contributors and developers who want to modify the code:

Option 1: Using uv (recommended for development)#

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# Install dependencies, including the dev group
# (`dev` is a PEP 735 dependency group, so plain `uv sync` installs it —
#  this is what `make install-dev` runs)
uv sync

# Runtime dependencies only, without the dev group
uv sync --no-dev

Optional extras#

One extra ships: [reranker], which adds cross-encoder relevance reranking over Xapian’s results.

uv tool install "openzim-mcp[reranker]"    # or: pip install "openzim-mcp[reranker]"
openzim-mcp download-models                 # required second step — see below

Installing it is not enough. The server never downloads the model (allow_model_download defaults to false, deliberately — an unannounced 1.1 GB fetch to HuggingFace would contradict what this server promises about reading only local archives). Without the second command, the first rerank-eligible query falls back to Xapian-only ranking and logs a warning.

Full details, including which platforms have wheels and how to turn rerank off without uninstalling, on Search reranking.

Option 2: Using pip (development)#

# Clone the repository
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install in development mode
pip install -e .

Setting Up ZIM Files#

Download ZIM Files#

One command, one real archive. A 13.6 MB extract of English Wikipedia on climate change, from the openZIM project’s own testing suite. Use it to confirm the install works before you commit to a multi-gigabyte download:

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

New-Item -ItemType Directory -Force -Path "$HOME\zim-files" | Out-Null
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/openzim/zim-testing-suite/main/data/withns/wikipedia_en_climate_change_mini_2024-06.zim" -OutFile "$HOME\zim-files\wikipedia_en_climate_change_mini_2024-06.zim"

Expect 14,239,035 bytes, SHA-256 72db7ae7708d3a4cff918495078901ec027b14b427433a2328286ec130d1c43b. It is an old-scheme archive, so its entry paths read A/Climate_change.

For real content — the Kiwix Library:

Visit browse.library.kiwix.org
Choose content: Wikipedia, Wiktionary, Stack Exchange, and more
Save the .zim into the same dedicated directory — the server takes directories, not individual files

Recommended ZIM Files for Testing#

Wikipedia climate-change mini: 13.6MB - the one-command download above
Simple English Wikipedia: ~200MB - Lightweight option
Wikipedia (English, Top 100): ~300MB - Good for testing
Wikipedia (English, Top 1000): ~2GB - Comprehensive testing

Platform-Specific Installation#

Windows#

Standard Installation:

# Install Python 3.12+ from python.org

# Install uv (the Linux/macOS installer on this page is POSIX-only)
irm https://astral.sh/uv/install.ps1 | iex

# Then install OpenZIM MCP
uv tool install openzim-mcp
# Or, with pip:
pip install openzim-mcp

Development Installation:

# Install Git from git-scm.com
# Clone and install
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# Using uv (recommended)
uv sync

# Or using pip
python -m venv venv
venv\Scripts\activate
pip install -e .

macOS#

Standard Installation:

# Install Python 3.12+ using Homebrew
brew install python@3.12

# Install OpenZIM MCP (uv recommended)
uv tool install openzim-mcp
# Or:
pip install openzim-mcp

Development Installation:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
uv sync

Linux (Ubuntu/Debian)#

Standard Installation:

# Install Python 3.12+
sudo apt update
sudo apt install python3.12 python3-pip

# Install OpenZIM MCP (uv recommended)
uv tool install openzim-mcp
# Or:
pip install openzim-mcp

Development Installation:

# Install development tools
sudo apt install python3.12-venv python3.12-dev git

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
uv sync

Linux (CentOS/RHEL/Fedora)#

Standard Installation:

# Install Python 3.12+
sudo dnf install python3.12 python3-pip

# Install OpenZIM MCP (uv recommended)
uv tool install openzim-mcp
# Or:
pip install openzim-mcp

Development Installation:

# Install development tools
sudo dnf install python3.12-venv python3.12-devel git

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
uv sync

Docker Installation#

OpenZIM MCP ships a multi-arch image at ghcr.io/cameronrye/openzim-mcp (linux/amd64 + linux/arm64). Runs as non-root (uid 10001). The image defaults to stdio transport, so it drops into an MCP client like the binary does.

# Pull
docker pull ghcr.io/cameronrye/openzim-mcp

# Run as a local stdio MCP server (default). -i keeps stdin open so the
# client can speak JSON-RPC over stdin/stdout. Mount ZIM files at /data.
docker run -i --rm -v /srv/zim:/data ghcr.io/cameronrye/openzim-mcp

The image entrypoint is python -m openzim_mcp /data, so mount your ZIM directory at /data. To run the long-running HTTP service instead, opt in at runtime — the server refuses to bind a non-loopback host without OPENZIM_MCP_AUTH_TOKEN:

docker run --rm -p 8000:8000 \
  -v /srv/zim:/data:ro \
  -e OPENZIM_MCP_TRANSPORT=http \
  -e OPENZIM_MCP_HOST=0.0.0.0 \
  -e OPENZIM_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  ghcr.io/cameronrye/openzim-mcp

For full deployment guidance (CORS, reverse proxy, healthchecks, systemd) see HTTP and Docker Deployment.

HTTP Transport (long-running service)#

For network access without Docker, use --transport http:

export OPENZIM_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
openzim-mcp --transport http --host 127.0.0.1 --port 8000 /srv/zim

The server refuses to bind a non-loopback host without an auth token as a safe default. For exposed deployments, terminate TLS at a reverse proxy (Caddy, nginx, traefik). See HTTP and Docker Deployment.

Verification#

Test the Installation#

Standard Installation:

# Test basic functionality
openzim-mcp --help

# Or using module
python -m openzim_mcp --help

# Run with a ZIM file directory
openzim-mcp /path/to/zim/files

Development Installation:

# Test basic functionality
uv run python -m openzim_mcp --help

# Run with a ZIM file directory
uv run python -m openzim_mcp /path/to/zim/files

# Run tests to verify everything works
make test

Expected Output#

2026-05-27 15:30:00,000 - openzim_mcp.main - INFO - OpenZIM MCP server started in SIMPLE mode (1 intelligent tool)
2026-05-27 15:30:00,001 - openzim_mcp.main - INFO - Allowed directories: /path/to/zim/files

Default mode is Simple (one natural-language tool). For all 8 tools (zim_query, zim_search, zim_get, zim_get_section, zim_browse, zim_metadata, zim_links, zim_health), pass --mode advanced.

The packaged distributions are the exception. The Docker image bakes OPENZIM_MCP_TOOL_MODE=advanced into the image, and the .mcpb extension’s manifest and the MCP Registry server.json set the same variable, so all three register all 8 tools with no flag. Pass -e OPENZIM_MCP_TOOL_MODE=simple if you want simple mode there.

MCP Client Configuration#

Almost every stdio MCP client takes the same shape — a server name, a command, and an args array. Only the file it lives in differs.

Start from this#

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "uvx",
      "args": ["openzim-mcp", "/path/to/zim/files"]
    }
  }
}

Why uvx rather than openzim-mcp directly. A GUI-launched client does not inherit your shell’s PATH, so a bare "command": "openzim-mcp" often fails with no such file or directory even though the command works fine in your terminal. uvx is usually on the system PATH because uv’s installer puts it there, and it resolves the package itself. This is what the project’s own server.json and the .mcpb bundle use.

If uvx is not found either, give the absolute path — which openzim-mcp (or which uvx) prints it.

Add "--mode", "advanced" before the directory to expose all 8 tools instead of just zim_query. Repeat the directory argument for multiple archive folders.

Where each client keeps that config#

Client	Location
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows), `~/.config/claude/claude_desktop_config.json` (Linux)
Claude Code	`claude mcp add openzim-mcp -- uvx openzim-mcp /path/to/zim/files` — no file editing
VS Code / Cursor / Windsurf	An `mcp.json` (or the MCP section of settings) in the workspace or user profile; the object shape above is unchanged
Continue	`~/.continue/config.json`, under its MCP servers block
Zed	`settings.json`, under `context_servers`
Any other stdio client	It needs a command line, not JSON: `uvx openzim-mcp /path/to/zim/files`

Client config schemas move faster than this page can track — if a client rejects the block above, check its own MCP documentation for the wrapper key and keep the command/args pair as-is.

One-click and registry installs#

Two routes skip configuration entirely:

Claude Desktop extension — download the openzim-mcp-<version>.mcpb asset from the latest release and double-click it. It prompts for your ZIM directory and pins the version. Requires uv on the host.
Smithery — npx @smithery/cli mcp add rye/openzim-mcp --client claude.

OpenZIM MCP is also listed on the official MCP Registry as io.github.cameronrye/openzim-mcp, so any client that reads the registry can install it by name.

Claude Desktop#

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Standard Installation (Recommended):

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "uvx",
      "args": ["openzim-mcp", "/path/to/zim/files"]
    }
  }
}

Claude Desktop is GUI-launched, so it does not inherit your shell’s PATH — a bare "command": "openzim-mcp" is the most common cause of “server failed to start” here even when the command works in a terminal.

Alternative (using Python module):

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "python",
      "args": [
        "-m",
        "openzim_mcp",
        "/path/to/zim/files"
      ]
    }
  }
}

Development Installation:

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/openzim-mcp",
        "run",
        "python",
        "-m",
        "openzim_mcp",
        "/path/to/zim/files"
      ]
    }
  }
}

Other MCP Clients#

Standard Installation:

openzim-mcp /path/to/zim/files

Development Installation:

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

Troubleshooting Installation#

Common Issues#

Python Version Error

Error: Python 3.12+ required

Solution: Install Python 3.12 or higher from python.org

uv Not Found

Command 'uv' not found

Solution: Install uv using the installation script or use pip instead

Permission Denied

Permission denied: '/path/to/zim/files'

Solution: Ensure the ZIM files directory is readable by the user running the server

ZIM Files Not Found

No ZIM files found in allowed directories

Solution: Download ZIM files from Kiwix Library and place them in the specified directory

Getting Help#

Check the Troubleshooting Guide for detailed solutions
Open an issue on GitHub

Next Steps#

Quick start — Learn basic usage
Configuration Guide — Customize your setup
API Reference — Explore available tools

Installation complete! Continue with the Quick start to start using OpenZIM MCP.

The v1.x maintenance window closed when v2.5.0 shipped (2026-06-18); only the current major line is supported — see SECURITY.md for the policy. The CHANGELOG carries the v1 → v2 migration table and the v3.0.0 breaking-changes entry.