mcpzim

Ein MCP-Server, der eine Gruppe von Offline-ZIM-Dateien für lokale LLM-Agenten verfügbar macht. Geben Sie ein Verzeichnis mit ZIM-Dateien an, und der Server wird:

• Den Inhalt inventarisieren (list_libraries) und aggregierte Funktionen (Allgemeinwissen, medizinisches Wissen, Karten/Routenplanung) basierend auf den geladenen Dateien bewerben.

• Suche und Artikelabruf für jede ZIM-Datei bereitstellen (search, get_article, get_main_page).

• Wenn er eine streetzim-ZIM-Datei erkennt, die mit --routing erstellt wurde, stellt er zusätzlich plan_driving_route, geocode und route_from_places bereit, sodass ein lokaler Agent fragen kann: "Gib mir eine Fahrtroute von A nach B" und Wegbeschreibungen, Distanz sowie eine geschätzte Zeit erhält.

Das Designprinzip ist opportunistische Funktionalität: Starten Sie mit einer Wikipedia-ZIM-Datei und Sie erhalten einen Wikipedia-Server. Fügen Sie mdwiki_en_all_*.zim hinzu, und er beantwortet auch medizinische Fragen. Fügen Sie eine streetzim-ZIM-Datei hinzu, und er kann auch Fahrtrouten für das von der ZIM-Datei abgedeckte Gebiet planen. Tools erscheinen nur, wenn die zugrunde liegenden Daten vorhanden sind, sodass die Tool-Liste des Agenten niemals falsche Versprechungen über die Fähigkeiten des Servers macht.

Installation

Erfordert Python 3.10+.

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

libzim ist ein natives Wheel; vorgefertigte Wheels existieren für macOS (x86_64/arm64), Linux (x86_64/aarch64, glibc und musl) und Windows x64. Auf anderen Plattformen baut pip aus dem Quellcode, und Sie benötigen eine C++-Toolchain.

Related MCP server: kiwix-mcp

Ausführung

Legen Sie Ihre ZIM-Dateien in ein Verzeichnis und führen Sie Folgendes aus:

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

Fügen Sie dies zu ~/.config/claude-desktop/claude_desktop_config.json (oder dem Äquivalent für Ihren MCP-Client) hinzu:

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

Tools

Immer verfügbar:

Nur vorhanden, wenn eine streetzim-ZIM-Datei mit Routing-Daten geladen ist:

Kosten/Heuristik im Router entsprechen exakt dem JS-Viewer von streetzim: edge_cost = distance_m / (speed_kmh / 3.6) und heuristic = haversine / (100/3.6), daher sind die Ergebnisse identisch mit denen, die der Browser-Viewer erzeugen würde.

Unterstützte ZIM-Dateien

Die Typenerkennung erfolgt zur Scan-Zeit und verwendet eine Kombination aus Dateinamen-Präfix, den Name / Tags / Creator / Publisher-Metadaten der ZIM-Datei sowie Signatureinträgen innerhalb des Archivs. Standardmäßig unterstützt:

• Wikipedia — jede wikipedia_*.zim (Creator: Wikipedia, getaggt mit wikipedia).

• mdwiki — mdwiki_*.zim von der WikiProjectMed Foundation (getaggt mit mdwiki / medical).

• streetzim — erkannt durch das Vorhandensein von routing-data/graph.bin oder map-config.json innerhalb des Archivs.

• generic — alles andere (eine *.zim wird trotzdem bereitgestellt; nur das Standard-Toolset ZimKind.GENERIC wird angewendet).

Beispiel-Sitzung

> 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], ...]}

Mobil

Die ehrliche Antwort: Das Ausführen von nativem Python + libzim auf iOS ist derzeit mühsam, da python-libzim keine iOS-Wheels hat und Sie die C++-libzim selbst cross-kompilieren müssten. Praktische Optionen, in der Reihenfolge des Aufwands:

1. LAN-Brücke (am einfachsten, funktioniert jetzt). Führen Sie mcpzim --transport streamable-http --host 0.0.0.0 auf einem Computer in Ihrem Netzwerk (oder einem Raspberry Pi) aus. Verbinden Sie Ihren mobilen Agenten damit. Die ZIM-Daten bleiben auf dem Heimserver; Ihr Telefon sieht nur einen funktionsreichen MCP-Endpunkt. Dies funktioniert heute ohne mobilen Code.

2. Android via Termux. pkg install python clang && pip install mcpzim in Termux baut libzim aus dem Quellcode. Führen Sie es auf dem Gerät aus, stellen Sie es über stdio (für einen lokalen Agentenprozess) oder streamable-http auf localhost für In-App-Clients bereit.

3. Swift/Kotlin-Port. Das SZRG v2-Routing-Format und die ZIM-Zugriffsschicht sind beide absichtlich unkompliziert. Ein Swift-MCP-Modul, das die C++-libzim über ihre Swift-Bindings aufruft (wie es Kiwix iOS bereits tut), könnte dieselbe Tool-Oberfläche wie dieser Python-Server bereitstellen. Das ist der beste Weg für eine iOS-Chat-App, die einen In-Process-MCP-Tool-Anbieter wünscht.

4. Kiwix-serve-Brücke. Die mobilen Kiwix-Apps betten bereits einen lokalen HTTP-Server ein; ein alternativer mcpzim-Modus, der an http://localhost:port/ weiterleitet, anstatt ZIM-Dateien direkt zu öffnen, würde überall dort funktionieren, wo Kiwix läuft. (Noch nicht implementiert — Pull Requests sind willkommen.)

Entwicklung

pip install -e '.[dev]'
pytest

Tests erfordern keine echten ZIM-Dateien; die Routing-Tests erstellen einen kleinen SZRG v2-Graphen im Arbeitsspeicher unter Verwendung von mcpzim.routing.encode_graph_v2, und die Bibliothekstests prüfen den Klassifikator direkt.

Lizenz

MIT.