# openzim-mcp

Lets an AI agent read ZIM archives — Wikipedia, Wiktionary, Stack Exchange — with no internet. Useful when search and navigation over a local knowledge base is what you need.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 146
- Author: cameronrye
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cameronrye/openzim-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/openzim-mcp

## What it does

The server exposes local access to ZIM files from the Kiwix library. Eight tools ship inside: `zim_query`, `zim_search`, `zim_get`, `zim_get_section`, `zim_browse`, `zim_metadata`, `zim_links`, `zim_health`. A Simple mode swaps all of that for one natural-language tool. Archive-type presets tune retrieval per source, so Wikipedia and Stack Exchange behave differently, and inbound link discovery answers what links here.

Transport is stdio or Streamable HTTP. Search returns suggestions and can span several archives at once; results are cached and paginated. Input validation and path-traversal protection are built in, along with MCP resources that notify on changes.

Without a `.zim` file the server has nothing to read, so drop an archive into the directory you point it at first. Install with `uv tool install openzim-mcp` or `pip install openzim-mcp`; the Docker image is `ghcr.io/cameronrye/openzim-mcp`. The container speaks stdio by default, which means `docker run -i` wires into an MCP client exactly like the binary does.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `OPENZIM_MCP_TOOL_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env OPENZIM_MCP_TOOL_MODE=<OPENZIM_MCP_TOOL_MODE> --transport stdio openzim-mcp -- uvx openzim-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openzim-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add openzim-mcp --env OPENZIM_MCP_TOOL_MODE=<OPENZIM_MCP_TOOL_MODE> -- uvx openzim-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openzim-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "openzim-mcp": {
            "command": "uvx",
            "args": [
                "openzim-mcp"
            ],
            "env": {
                "OPENZIM_MCP_TOOL_MODE": "<OPENZIM_MCP_TOOL_MODE>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openzim-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "openzim-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "openzim-mcp"
            ],
            "env": {
                "OPENZIM_MCP_TOOL_MODE": "<OPENZIM_MCP_TOOL_MODE>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openzim-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e OPENZIM_MCP_TOOL_MODE=<OPENZIM_MCP_TOOL_MODE> openzim-mcp uvx openzim-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openzim-mcp <command>

## When to use it
- find an article inside an offline Wikipedia archive
- pull a table of contents and sections from a ZIM page
- see which articles link to the current one
- search across several ZIM archives at once
- inspect archive metadata and health

## Example prompts
- Summarize the Photosynthesis article from the archive
- Show me the sections of the climate change article in `wikipedia_en_climate_change_mini_2024-06.zim`
- What links to this article in the archive?

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md