Skip to main content
Glama

Zimfo

Zimfo is an offline, on-device chat app (iOS + macOS) that answers questions from locally-loaded ZIM archives — Wikipedia, OpenStreetMap street data (streetzim), and medical (mdwiki) — using a local fine-tuned LLM that drives a tool loop over those archives. Nothing leaves the device.

Ask "tell me about the Duchy of Lithuania", "how do solar panels work?", "what's near me?", "how far is it to the cathedral?", or "compare Musk and Bezos" — Zimfo searches the ZIMs, reads the right article, and answers. Follow-ups ("tell me more", "yes", "what's near there?", "the second one") resolve against a deterministic on-device conversation focus rather than the small model's own memory, and a "let's discuss X" mode grounds multi-turn Q&A in retrieved article passages — so a walking conversation actually holds together.

Getting the content is now part of the app. A fresh install offers two paths to a working library: Nearby Sharing — a friend who already has Zimfo (the person who recommended it, usually) turns on Share my library and their Wikipedia/StreetZIM files — and the AI models: chat and voice — copy straight to the new device over AWDL / peer-to-peer Wi-Fi, no router or internet needed, with per-chunk SHA-256 verification, multi-device parallel pull, and resume (powered by the vendored LocalSwarm engine, ios/LocalPackages/LocalSwarm/); the received chat model drops into the provider's own cache slot and auto-activates, and the Kokoro/Supertonic voice folders land where the TTS engines look, so the whole bootstrap — reading and speaking — works with zero connectivity — and an in-app download catalog: Wikipedia editions with and without pictures plus the full StreetZIM region list, multi-selected and fetched by a background URLSession that keeps going while the app is suspended and keeps the device awake while it's frontmost. Either way, finished files land in the library and are ready to chat — and ready to share onward to the next person.

The shipping model is a LoRA-fine-tuned LFM2.5-8B-A1B (8.3B-total / 1.5B-active hybrid MoE) quantized to IQ3_XS with an importance matrix calibrated on the app's own tool-call transcripts: 12/13 on the tool-calling eval grid at ~3.6 GB peak RSS and ~136 t/s decode (M2 Max), running through llama.cpp with a 32k context and cross-turn KV prefix reuse (follow-up turns prefill ~23 tokens instead of the whole transcript). How we got here — the full stock-model sweep (Gemma 3/4, Qwen 3/3.5, Phi, …), the fine-tuning pivot, the Gemma 4 QAT/MTP investigation, and the quantization frontier — is written up in MODEL_EVALUATION_HISTORY.md.

This repo has three layers, smallest-dependency first:

  • The shared engine — swift/MCPZimKit: a transport-agnostic, Foundation-only Swift package. ZIM tool adapter, A* routing-graph parser + router, prefix geocoder, and the conversation-state machine (focus, reference resolution, drift threads). Exercised by swift test.

  • The app — ios/: the SwiftUI Zimfo app (on-device Gemma 4 / fine-tuned LFM2.5 via MLX + llama.cpp). Architecture and the pieces that took the most iteration are in docs/ARCHITECTURE.md. Siri integration is covered by the research and implementation guide and iOS 27 phone acceptance checklist.

  • The reusable kernel — the mcpzim MCP server (Python): the original backend, documented below. It exposes the same ZIM tools to any agent host over MCP, so the engine isn't locked to the app.

The mcpzim MCP server (Python)

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.

Related MCP server: ZimAgent

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:

Tool

What it does

list_libraries

Inventory: list every ZIM with kind, title, language, and the aggregate capabilities (general_knowledge, medical, maps, ...). Call this first.

search

Full-text search across every ZIM (uses libzim's Xapian index when present, falls back to title-prefix suggestions). Accepts an optional kind filter.

get_article

Fetch an entry by path; HTML is stripped of navbox / infobox / script cruft so the LLM sees clean text.

get_main_page

Main page of one ZIM, or of every loaded ZIM.

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

Tool

What it does

plan_driving_route

A* over the streetzim routing graph. Input: two lat/lon pairs. Output: total distance, duration, polyline, and a road-segment list coalesced by street name.

geocode

Resolve a place/address string to coordinates using streetzim's prefix-chunked search index.

route_from_places

Convenience: geocode both endpoints then plan a route.

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:

Platform

LLM host

Path

Status

Desktop

Claude Desktop / Code, any MCP client

This Python server via stdio or streamable-http

Works today

Android

Google AI Edge Gallery (Gemma 4 + LiteRT-LM, Apache 2.0)

Small Kotlin fork — add a @Tool fun callMcp(...) that talks JSON-RPC/HTTP to this Python server

See mobile/android/README.md — ~80 lines of Kotlin + one SKILL.md

Android (fully offline)

same

Run mcpzim under Termux on the same device

Works; Termux has to build libzim from source (pkg install python clang cmake)

iOS

The Zimfo app in this repo (ios/) — fine-tuned LFM2.5 via llama.cpp (+ MLX models)

Links swift/MCPZimKit — pure-Swift routing graph parser, A*, geocoder, transport-agnostic MCP tool adapter, conversation-state machine — with a ZimReader backed by CoreKiwix.xcframework.

Works today — see docs/ARCHITECTURE.md

iOS

Google AI Edge Gallery (closed-source app)

Available on the App Store since 2026-04 with Gemma 4 support — fine for trying models, but no tool-calling hook into this server.

Demo-only

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.

Available Tools

4 tools
get_articleA

Fetch a single article by path, as plain text ready for reading.

Args: path: the ZIM entry path (as returned in search results, e.g. A/Aspirin). zim: optional filename or path of the ZIM to read from. If omitted, all loaded ZIMs are tried in scan order.

Inputs: path (required), zim.

get_main_pageB

Fetch the main/home page of a ZIM. If no zim name is given, returns the main page of every loaded ZIM.

Inputs: zim.

list_librariesA

Inventory the ZIM archives this server can read.

Returns a list of archives with their kind (wikipedia / mdwiki / streetzim / generic), metadata, and the aggregate capabilities exposed (e.g. plan_route is only present when a streetzim ZIM is loaded). Call this first so you know what sources and tools are available.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_article fetches a specific article, get_main_page retrieves the main page, list_libraries inventories available archives, and search performs full-text queries. The descriptions clearly differentiate their functions, eliminating any ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_article, get_main_page, list_libraries, search), with 'search' being a concise exception that still fits the verb-first style. The naming is uniform and predictable across the set.

    Tool Count5/5

    With 4 tools, this server is well-scoped for its purpose of accessing ZIM archives. Each tool earns its place by covering essential operations: inventorying sources, retrieving content (specific articles and main pages), and searching. The count is neither too sparse nor bloated.

    Completeness5/5

    The tool set provides complete coverage for the domain of reading and searching ZIM archives. It includes discovery (list_libraries), content retrieval (get_article, get_main_page), and search capabilities, with no obvious gaps. Agents can navigate from listing to fetching or searching seamlessly.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      An MCP server that enables interaction with Kiwix HTTP servers to browse, search, and retrieve content from offline ZIM books like Wikipedia. It provides tools for listing available library resources and fetching full-text articles as plain text.
      3
      10
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables offline CRUD and semantic search on Wikipedia ZIM archives via MCP tools for reading, writing, editing, deleting, and searching articles.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for reading and searching ZIM archives, optimized for single-user deployments with a persistent Wikipedia archive.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive local offline MCP server with over 300 tools for file operations, office documents, PDFs, code execution, databases, web browsing, memory, and cognitive functions, designed to work offline except for web search and email.
      MIT