The mcpzim server provides local LLM agents with offline access to ZIM archives (Wikipedia, medical wikis, maps) for knowledge retrieval and, optionally, routing.
list_libraries — Inventory all loaded ZIM archives, their types (wikipedia, mdwiki, streetzim, generic), metadata, and aggregate capabilities. Call this first to understand what sources are active.
search — Full-text search across all loaded ZIMs, with optional kind filter and configurable result limit. Returns source ZIM, path, title, and snippet per hit.
get_article — Fetch a specific article by its ZIM entry path as clean plain text (HTML cruft stripped). Optionally target a specific ZIM file.
get_main_page — Retrieve the main/home page of a specific ZIM, or all loaded ZIMs if none is specified.
Conditional (requires a streetzim archive with routing data):
geocode — Resolve a place name or address string to geographic coordinates.
plan_driving_route — Compute an A* driving route between two lat/lon pairs, returning distance, duration, polyline, and road segments.
route_from_places — Convenience tool that geocodes an origin and destination, then plans a driving route between them.
Everything runs fully offline; no data leaves the device.
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 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.
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.
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
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.
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" }
}
}
}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.
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).
> 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], ...]}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.
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.
MIT.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| zim | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the article is fetched 'as plain text ready for reading', which adds context about the output format. However, it lacks details on error handling (e.g., what happens if the path is invalid), performance (e.g., speed or size limits), or side effects, leaving gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a structured 'Args:' section that efficiently explains parameters without redundancy. Every sentence adds value, and there is no wasted text, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose and parameters well but lacks information on return values (since no output schema exists), error conditions, or dependencies on sibling tools. This leaves some gaps for an AI agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It provides clear semantics for both parameters: 'path' is explained as 'the ZIM entry path (as returned in search results, e.g., ``A/Aspirin``)', and 'zim' is described as 'optional filename or path of the ZIM to read from' with behavior when omitted. This adds meaningful context beyond the bare schema, though it could include examples or constraints for 'zim'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch a single article by path') and resource ('article'), distinguishing it from sibling tools like 'list_libraries' (which lists libraries) and 'search' (which searches across content). It also specifies the output format ('as plain text ready for reading'), which further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'as returned in search results' for the path parameter, suggesting it should be used after a search. However, it does not explicitly state when to use this tool versus alternatives like 'get_main_page' or provide exclusions, leaving some ambiguity about the ideal context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the main/home page of a ZIM. If no zim name is given, returns the main page of every loaded ZIM.
| Name | Required | Description | Default |
|---|---|---|---|
| zim | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the conditional behavior based on the 'zim' parameter, which is useful. However, it lacks details on permissions, rate limits, error handling, or what 'loaded ZIM' means in practice. For a tool with no annotations, this leaves significant gaps in understanding its operational traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—just two sentences—with zero wasted words. It front-loads the core purpose and efficiently explains the parameter's effect. Every sentence earns its place by adding critical information, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and parameter semantics adequately. However, without annotations or output schema, it should ideally mention more about behavioral aspects like return format or error cases. It's minimally viable but could be more comprehensive for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'zim': it explains that if no zim name is given, it returns the main page of every loaded ZIM. This clarifies the parameter's optional nature and its impact on behavior. Since schema description coverage is 0%, the description compensates well by providing semantic understanding beyond the bare schema, though it could specify what a 'zim name' format entails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('main/home page of a ZIM'), making the purpose understandable. It distinguishes from siblings like 'get_article' by focusing on the main page rather than specific articles, though it doesn't explicitly contrast them. The purpose is specific but could be more precise about what a 'main page' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it by stating the conditional behavior: use with a zim name to fetch a specific ZIM's main page, or without to get all loaded ZIMs' main pages. However, it doesn't provide explicit guidance on when to choose this tool over alternatives like 'list_libraries' or 'search', nor does it mention any prerequisites or exclusions. The usage context is implied but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by specifying the return format ('list of archives with their kind, metadata, and aggregate capabilities') and implying it's a read-only inventory operation (no destructive actions mentioned). However, it lacks details on potential errors, rate limits, or authentication requirements, which are minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by details on returns and usage guidance. Every sentence earns its place: the first explains what it does, the second details the output, and the third provides critical context on when to use it. There is no wasted text, and it's structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple inventory with 0 parameters) and lack of annotations/output schema, the description is largely complete. It covers purpose, output details, and usage context. However, it doesn't specify the exact structure of the returned list or error handling, which are minor omissions for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately focuses on output semantics, explaining what information is returned (e.g., archive kinds, metadata, capabilities like 'plan_route'). This adds value beyond the empty input schema, justifying a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Inventory') and resource ('ZIM archives this server can read'), distinguishing it from sibling tools like get_article, get_main_page, and search by focusing on system inventory rather than content retrieval. It explicitly mentions what is returned ('list of archives with their kind, metadata, and aggregate capabilities'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Call this first so you know what sources and tools are available.' This indicates it should be used as an initial step to discover available resources before invoking other tools, clearly differentiating it from siblings that perform content operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No | ||
| kind | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the scope ('across all loaded ZIMs') and describes the return format ('Each hit includes the source ZIM, path, title and a short snippet'), but doesn't address important behavioral aspects like whether this is a read-only operation, performance characteristics, error conditions, or pagination behavior. For a search tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It begins with the core purpose statement, then provides a well-organized parameter section with clear explanations for each parameter. Every sentence earns its place, and the information is front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (search across multiple ZIMs), no annotations, no output schema, and 3 parameters, the description provides adequate but incomplete coverage. It explains parameters well and describes the return format, but lacks information about authentication requirements, rate limits, error handling, or the relationship between 'limit per ZIM' and total results across multiple ZIMs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the lack of parameter documentation in the schema. The description successfully adds meaning for all three parameters: explaining 'query' as 'search terms', 'limit' as 'max results per ZIM' with default value, and 'kind' as an 'optional filter' with enumerated values. This provides clear semantic understanding beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'Full-text search across all loaded ZIMs' which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'get_article' (retrieves specific content), 'get_main_page' (gets homepage), and 'list_libraries' (lists available libraries). However, it doesn't explicitly contrast with these siblings in the description text itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through the phrase 'across all loaded ZIMs' and the parameter documentation, but doesn't explicitly state when to use this tool versus alternatives. No guidance is provided about when not to use it or what specific scenarios warrant choosing 'search' over sibling tools like 'get_article' for direct content retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_articleget_main_pagelist_librariessearchScored 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.
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.
