Quick start

Get up and running with OpenZIM MCP in just a few minutes. This tutorial walks through your first successful setup and usage in simple mode (the default, one natural-language tool), then shows one advanced mode example using the 8-tool advanced surface.

What you’ll learn#

How to set up OpenZIM MCP with a test ZIM file
How to configure your MCP client
How to dispatch zim_query in simple mode
How to use zim_search (and friends) in advanced mode
How to verify everything is working correctly

Time required: ~5 minutes#

Before you start#

Make sure you have completed the Installation page and have:

OpenZIM MCP installed (uv tool install openzim-mcp or pip install openzim-mcp)
Python 3.12+ available
A ZIM file downloaded (we’ll help you get one if needed)

Notation: examples on this page use MCP JSON-RPC tool-call framing ({"name": "...", "arguments": {...}}). Your MCP client (Claude Desktop, etc.) handles the wire framing; you only need to know the tool name and argument shape.

Step 1: Get a test ZIM file#

Option A: one command (recommended)#

A real 13.6 MB extract of English Wikipedia on climate change, from the openZIM project’s own testing suite, at a stable URL. Nothing to install and no account:

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

Windows PowerShell:

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"

You should get 14,239,035 bytes, SHA-256 72db7ae7708d3a4cff918495078901ec027b14b427433a2328286ec130d1c43b (shasum -a 256 <file> on macOS, sha256sum on Linux, Get-FileHash on Windows).

This archive uses the older namespace scheme, so its entry paths read A/Climate_change rather than C/Climate_change. Both appear in these docs; see ZIM concepts for why.

Option B: a bigger archive from the Kiwix library#

For anything past a first run, browse browse.library.kiwix.org — Wikipedia, Wiktionary, Stack Exchange and more — and save the .zim into the same ~/zim-files directory. “Wikipedia English Top 100” (~300 MB) is a reasonable second archive.

Option C: the project’s test corpus (development)#

# From your openzim-mcp source checkout
make download-test-data       # the two priority-1 fixtures (79 KB + 41 KB)
make download-test-data-all   # the whole suite, malformed archives included

Both write into test_data/zim-testing-suite/. The default target fetches only withns/small.zim and nons/small.zim — enough for the test suite, too small to explore, which is why Option A exists. Either target leaves more than one .zim in the directory, which changes how archive auto-selection behaves; see the note at the end of Step 4.

Step 2: Start the server (simple mode)#

Simple mode is the default. It exposes a single natural-language tool, zim_query, that dispatches to the right underlying operation based on the request.

# Start the server with your ZIM files directory
openzim-mcp ~/zim-files

# You should see two log lines like:
# 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: /home/user/zim-files

For network access (long-running service, browser clients, Docker), use --transport http and see HTTP and Docker Deployment.

Development installation:

# Navigate to your openzim-mcp directory
cd /path/to/openzim-mcp

# Start the server with your ZIM files directory
uv run python -m openzim_mcp ~/zim-files

Step 3: Configure your MCP client#

For Claude Desktop#

Find your 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
Add OpenZIM MCP configuration:

Standard Installation (Recommended):

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

Development Installation:

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

Restart Claude Desktop.

For Other MCP Clients#

Standard Installation:

openzim-mcp /path/to/zim-files

Development Installation:

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

Step 4: Try simple mode (`zim_query`)#

In simple mode, the server exposes one tool. Phrase the request in plain language; the dispatcher routes it to the right underlying operation.

Summarize an article#

{
  "name": "zim_query",
  "arguments": {
    "query": "summarize Photosynthesis"
  }
}

Expected response: a summary block for the Photosynthesis article. The Step 1 Option A archive is a climate-change extract with no Photosynthesis entry, so it answers with the nearest article it does hold (A/Artificial_photosynthesis) — swap in a topic your archive covers to see the exact-match path.

With more than one archive in the directory, add zim_file_path. There is no cross-archive scan on this path: the server auto-selects an archive only when exactly one is present. With two or more it returns a No ZIM File Specified prompt instead. This matters immediately if you ran make download-test-data, which fetches two .zim files.

List available ZIM files#

{
  "name": "zim_query",
  "arguments": {
    "query": "list available ZIM files"
  }
}

Expected response: the set of ZIM files in your allowed directories, with sizes and modification times.

Search across content#

{
  "name": "zim_query",
  "arguments": {
    "query": "search for biology"
  }
}

Expected response: ranked search results with snippets and entry paths.

Fetch an article#

{
  "name": "zim_query",
  "arguments": {
    "query": "get article Evolution"
  }
}

Expected response: the rendered article body. (Server health and cache stats are an advanced-mode feature — the zim_health tool; the simple-mode intent parser has no health operation.)

Step 5: Try advanced mode (`zim_search` + friends)#

When you need precise control — a specific search mode, cross-file scope, suggestion-style title resolution — start the server in advanced mode, which exposes the full 8-tool advanced surface: zim_query, zim_search, zim_get, zim_get_section, zim_browse, zim_metadata, zim_links, zim_health.

openzim-mcp --mode advanced ~/zim-files

A focused full-text search#

{
  "name": "zim_search",
  "arguments": {
    "zim_file_path": "/home/user/zim-files/wikipedia_en_100.zim",
    "mode": "fulltext",
    "query": "photosynthesis light reaction",
    "limit": 10
  }
}

Expected response: up to 10 ranked full-text hits with snippets and entry paths. From here, the LLM can call zim_get with one of the returned paths to retrieve the full article, or zim_links(direction="outbound", ...) to extract outgoing links.

Step 6: Verify everything works#

Smoke test#

In simple mode, run a search and then a retrieval as two calls — the dispatcher handles one operation per call and answers a chained request (“search for X, then get article Y”) with guidance to split it:

{
  "name": "zim_query",
  "arguments": {
    "query": "search for computer"
  }
}

then

{
  "name": "zim_query",
  "arguments": {
    "query": "get article Computer"
  }
}

This exercises both search and content retrieval.

Success! What’s next?#

You now have OpenZIM MCP running successfully. Here’s what to explore next:

Learn more#

API Reference — every tool, prompt, and resource (8-tool advanced surface)
LLM Integration Patterns — best practices for AI integration
Configuration Guide — customize your setup

Advanced usage#

Performance Optimization — optimize for production
Security Best Practices — secure your deployment
Architecture Overview — understand the system design

Development#

Contributing Guidelines — contribute, run tests, and use the dev workflow

Troubleshooting#

Common issues#

“No ZIM files found”

Verify ZIM files are in the correct directory
Check file permissions
Ensure files have .zim extension

“Server not responding”

Check if the server process is running
Verify the correct path in MCP client configuration
Look for error messages in the server output

“Permission denied”

Ensure the user has read access to ZIM files directory
Check directory permissions

Getting help#

Troubleshooting Guide — detailed solutions
GitHub Issues — report bugs and ask questions

Pro tips#

Start small: use smaller ZIM files (100–500MB) for initial testing.
Monitor performance: use the zim_health tool in advanced mode to monitor cache performance (simple mode has no health operation).
Experiment: try different search terms and content types to understand capabilities.
Read the logs: server logs provide valuable debugging information.

Great job! You’re now ready to harness the full power of OpenZIM MCP for your AI applications. Happy exploring.

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.