mcpzim

Un servidor MCP que pone a disposición de agentes LLM locales un grupo de archivos ZIM sin conexión. Apúntalo a un directorio de ZIMs y el servidor hará lo siguiente:

• Inventariar lo que hay (list_libraries) y anunciar capacidades agregadas (conocimiento general, conocimiento médico, mapas/rutas) según lo que esté cargado.

• Exponer la búsqueda y recuperación de artículos en cada ZIM (search, get_article, get_main_page).

• Cuando detecta un ZIM de streetzim construido con --routing, expone adicionalmente plan_driving_route, geocode y route_from_places para que un agente local pueda preguntar "dame una ruta de conducción de A a B" y obtener indicaciones calle por calle, distancia y un tiempo estimado.

El principio de diseño es la capacidad oportunista: empieza con un ZIM de Wikipedia y obtendrás un servidor de Wikipedia. Añade mdwiki_en_all_*.zim y también responderá preguntas médicas. Añade un ZIM de streetzim y también podrá planificar rutas de conducción para el área que cubre el ZIM. Las herramientas aparecen solo cuando los datos subyacentes están presentes, por lo que la lista de herramientas del agente nunca miente sobre lo que el servidor puede hacer.

Instalación

Requiere Python 3.10+.

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

libzim es un wheel nativo; existen wheels precompilados para macOS (x86_64/arm64), Linux (x86_64/aarch64, glibc y musl) y Windows x64. En otras plataformas, pip compilará desde el código fuente y necesitarás una cadena de herramientas C++.

Related MCP server: kiwix-mcp

Ejecución

Coloca tus archivos ZIM en un directorio y ejecuta:

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

Añádelo a ~/.config/claude-desktop/claude_desktop_config.json (o el equivalente para tu cliente MCP):

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

Herramientas

Siempre disponibles:

Solo presente cuando se carga un ZIM de streetzim con datos de enrutamiento:

El coste/heurística en el enrutador coincide exactamente con el visor JS de streetzim: edge_cost = distance_m / (speed_kmh / 3.6) y heuristic = haversine / (100/3.6), por lo que los resultados son idénticos a lo que produciría el visor en el navegador.

ZIMs soportados

La detección de tipo se ejecuta en el momento del escaneo y utiliza una combinación de prefijo de nombre de archivo, metadatos Name / Tags / Creator / Publisher del ZIM y entradas de firma dentro del archivo. De forma predeterminada:

• Wikipedia — cualquier wikipedia_*.zim (Creator: Wikipedia, etiquetado como wikipedia).

• mdwiki — mdwiki_*.zim de la WikiProjectMed Foundation (etiquetado como mdwiki / medical).

• streetzim — detectado por la presencia de routing-data/graph.bin o map-config.json dentro del archivo.

• genérico — cualquier otra cosa (un *.zim sigue siendo servido; solo se aplica el conjunto de herramientas predeterminado ZimKind.GENERIC).

Sesión de ejemplo

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

Móvil

La respuesta honesta: ejecutar Python nativo + libzim en iOS es doloroso hoy en día porque python-libzim no tiene wheels para iOS y tendrías que realizar la compilación cruzada de libzim en C++ tú mismo. Opciones prácticas, en orden de esfuerzo:

1. Puente LAN (más fácil, funciona ahora). Ejecuta mcpzim --transport streamable-http --host 0.0.0.0 en una máquina de tu red (o una Raspberry Pi). Apunta tu agente móvil hacia ella. Los datos ZIM permanecen en el servidor doméstico; tu teléfono solo ve un endpoint MCP rico en capacidades. Esto funciona hoy sin código móvil.

2. Android vía Termux. pkg install python clang && pip install mcpzim en Termux compila libzim desde el código fuente. Ejecútalo en el dispositivo, exponlo vía stdio (a un proceso de agente local) o streamable-http en localhost para clientes dentro de la aplicación.

3. Puerto Swift/Kotlin. El formato de enrutamiento SZRG v2 y la capa de acceso ZIM son intencionalmente sencillos. Un módulo MCP en Swift que llame a libzim en C++ a través de sus enlaces Swift (como ya hace Kiwix iOS) podría exponer la misma superficie de herramientas que este servidor Python. Ese es el mejor camino para una aplicación de chat en iOS que quiera un proveedor de herramientas MCP en proceso.

4. Puente Kiwix-serve. Las aplicaciones móviles de Kiwix ya integran un servidor HTTP local; un modo alternativo de mcpzim que haga proxy a http://localhost:port/ en lugar de abrir ZIMs directamente funcionaría dondequiera que se ejecute Kiwix. (Aún no implementado — las PR son bienvenidas.)

Desarrollo

pip install -e '.[dev]'
pytest

Las pruebas no requieren archivos ZIM reales; las pruebas de enrutamiento construyen un pequeño grafo SZRG v2 en memoria usando mcpzim.routing.encode_graph_v2, y las pruebas de la biblioteca ejercitan el clasificador directamente.

Licencia

MIT.