mcpzim

An MCP server that makes a group of offline ZIM files available to local LLM agents. Point it at a directory of ZIMs and the server will:

• Inventory what's there (list_libraries) and advertise aggregate capabilities (general knowledge, medical knowledge, maps/routing) based on what's loaded.

• Expose search and article retrieval across every ZIM (search, get_article, get_main_page).

• When it detects a streetzim ZIM built with --routing, it additionally exposes plan_driving_route, geocode, and route_from_places so a local agent can ask "give me a driving route from A to B" and get street-by-street directions, distance, and an estimated time.

The design principle is opportunistic capability: start with one Wikipedia ZIM and you get a Wikipedia server. Drop in mdwiki_en_all_*.zim and it also answers medical questions. Drop in a streetzim ZIM and it can also plan driving routes for the area the ZIM covers. Tools appear only when the underlying data is present, so the agent's tool list never lies about what the server can do.

Install

Requires Python 3.10+.

pip install mcpzim               # once published
# or, from a checkout:
pip install -e .

libzim is a native wheel; prebuilt wheels exist for macOS (x86_64/arm64), Linux (x86_64/aarch64, glibc and musl) and Windows x64. On other platforms pip will build from source and you'll need a C++ toolchain.

Run

Drop your ZIM files into one directory and run:

export ZIM_DIR=~/zims
mcpzim                           # stdio transport (Claude Desktop / Code)
mcpzim ~/zims/wikipedia.zim ~/zims/streetzim_ma.zim   # explicit paths
mcpzim --transport streamable-http --host 0.0.0.0 --port 8765  # LAN

Add to ~/.config/claude-desktop/claude_desktop_config.json (or the equivalent for your MCP client):

{
  "mcpServers": {
    "mcpzim": {
      "command": "mcpzim",
      "env": { "ZIM_DIR": "/Users/me/zims" }
    }
  }
}

Tools

Always available:

Only present when a streetzim ZIM with routing data is loaded:

Cost/heuristic in the router match streetzim's JS viewer exactly: edge_cost = distance_m / (speed_kmh / 3.6) and heuristic = haversine / (100/3.6), so results are identical to what the in-browser viewer would produce.

Supported ZIMs

Type detection runs at scan time and uses a combination of filename prefix, the ZIM's Name / Tags / Creator / Publisher metadata, and signature entries inside the archive. Out of the box:

• Wikipedia — any wikipedia_*.zim (Creator: Wikipedia, tagged wikipedia).

• mdwiki — mdwiki_*.zim from the WikiProjectMed Foundation (tagged mdwiki / medical).

• streetzim — detected by the presence of routing-data/graph.bin or map-config.json inside the archive.

• generic — anything else (a *.zim still gets served; only the ZimKind.GENERIC default toolset applies).

Example session

> list_libraries
{"zims": [
   {"path": ".../wikipedia_en_all_nopic_2026-03.zim", "kind": "wikipedia", ...},
   {"path": ".../mdwiki_en_all_2026-03.zim", "kind": "mdwiki", ...},
   {"path": ".../streetzim_ma.zim", "kind": "streetzim", "has_routing": true, ...}
 ],
 "by_kind": {"wikipedia": 1, "mdwiki": 1, "streetzim": 1},
 "capabilities": ["encyclopedia", "general_knowledge", "geocode",
                  "get_article", "list_libraries", "maps", "medical",
                  "plan_route", "search"]}

> route_from_places {"origin": "Boston Common", "destination": "Fenway Park"}
{"origin_resolved": {"name": "Boston Common", "lat": 42.3554, "lon": -71.0655, ...},
 "destination_resolved": {"name": "Fenway Park", "lat": 42.3467, "lon": -71.0972, ...},
 "distance_km": 3.27, "duration_min": 9.4,
 "roads": [
    {"name": "Beacon Street", "distance_m": 412.3, "duration_s": 44.0},
    ...
 ],
 "turn_by_turn": ["Beacon Street for 0.41 km (~0.7 min)", ...],
 "polyline": [[42.3554, -71.0655], ...]}

Mobile

Concrete paths that actually work, matched to the on-device LLM hosts people are shipping in 2026:

The short version: on Android the open-source Agent Chat host already knows how to call a tool, so a short Kotlin patch makes it speak to this Python server. On iOS, the LLM host has no tool-calling layer yet, so the companion Swift package ships (a) the same algorithms in pure Swift for in-process use, and (b) a transport-agnostic MCP adapter you can plug into the official modelcontextprotocol/swift-sdk when you want the model to call tools over LAN.

swift/MCPZimKit's SZRG v2 parser, A* router, and prefix geocoder are line-for-line ports of the Python implementations; the Python test suite and the Swift test suite in swift/Tests/MCPZimKitTests/ cover the same cases, so if both green, you know the two agree.

Development

pip install -e '.[dev]'
pytest

Tests do not require any real ZIM files; the routing tests build a tiny SZRG v2 graph in-memory using mcpzim.routing.encode_graph_v2, and the library tests exercise the classifier directly.

License

MIT.