mcpzim
This server provides offline, local access to ZIM archive content (Wikipedia, mdwiki, streetzim, generic) for LLM agents via MCP tools.
list_libraries – inventory loaded ZIMs, their kind/metadata, and aggregate capabilities (e.g., general knowledge, medical, maps, routing).
search – full-text search across all ZIMs, with optional per-kind filtering and per-ZIM result limits.
get_article – fetch a clean, plain-text article by path from a specific ZIM or the first matching one.
get_main_page – retrieve the main page of one ZIM or all loaded ZIMs.
When a streetzim ZIM with routing data is loaded, additional tools appear:
geocode – resolve a place/address string to coordinates.
plan_driving_route – compute A* driving routes between two lat/lon points, returning distance, duration, road segments, and turn-by-turn directions.
route_from_places – convenience tool that geocodes both endpoints and plans a driving route.
Capabilities are opportunistic: tools are exposed only when the underlying data is present, so the tool list always reflects what the server can actually do.
Supports running on Android devices via Termux, allowing the MCP server to operate directly on Android with offline ZIM content access and routing capabilities.
Discusses potential integration approaches for iOS, including running as a LAN bridge or creating a Swift MCP module that leverages libzim bindings for in-app content access.
Integrates with Kiwix's ZIM file format and mentions potential future integration with Kiwix mobile apps' local HTTP server for serving content through the MCP server.
Provides access to offline Wikipedia content through ZIM files, enabling search and article retrieval for general knowledge queries without internet connectivity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcpzim search for information about the history of the Eiffel Tower"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 byswift 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 indocs/ARCHITECTURE.md. Siri integration is covered by the research and implementation guide and iOS 27 phone acceptance checklist.The reusable kernel — the
mcpzimMCP 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 exposesplan_driving_route,geocode, androute_from_placesso 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 # LANAdd 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 |
| Inventory: list every ZIM with kind, title, language, and the aggregate capabilities ( |
| Full-text search across every ZIM (uses libzim's Xapian index when present, falls back to title-prefix suggestions). Accepts an optional |
| Fetch an entry by path; HTML is stripped of navbox / infobox / script cruft so the LLM sees clean text. |
| 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 |
| A* over the streetzim routing graph. Input: two |
| Resolve a place/address string to coordinates using streetzim's prefix-chunked search index. |
| 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, taggedwikipedia).mdwiki —
mdwiki_*.zimfrom the WikiProjectMed Foundation (taggedmdwiki/medical).streetzim — detected by the presence of
routing-data/graph.binormap-config.jsoninside the archive.generic — anything else (a
*.zimstill gets served; only theZimKind.GENERICdefault 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 | Works today |
Android | Google AI Edge Gallery (Gemma 4 + LiteRT-LM, Apache 2.0) | Small Kotlin fork — add a | See |
Android (fully offline) | same | Run | Works; Termux has to build |
iOS | The Zimfo app in this repo ( | Links | Works today — see |
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]'
pytestTests 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 toolsget_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.
searchB
Full-text search across all loaded ZIMs.
Args:
query: search terms.
limit: max results per ZIM (default 10).
kind: optional filter, one of wikipedia, mdwiki,
streetzim, generic.
Each hit includes the source ZIM, path, title and a short snippet.
Inputs: query (required), limit, kind.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Hosted MCP server for live public-data APIs and Skills for AI agents.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Related MCP Servers
- FlicenseAqualityBmaintenanceAn 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.310-
- AlicenseNot gradedqualityDmaintenanceEnables offline CRUD and semantic search on Wikipedia ZIM archives via MCP tools for reading, writing, editing, deleting, and searching articles.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for reading and searching ZIM archives, optimized for single-user deployments with a persistent Wikipedia archive.MIT
- AlicenseNot gradedqualityDmaintenanceA 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