mcpzim

Сервер MCP, который делает группу автономных файлов ZIM доступными для локальных агентов LLM. Укажите путь к каталогу с ZIM-файлами, и сервер:

• Проведет инвентаризацию содержимого (list_libraries) и анонсирует совокупные возможности (общие знания, медицинские знания, карты/маршрутизация) на основе загруженных файлов.

• Предоставит инструменты поиска и получения статей по всем ZIM-файлам (search, get_article, get_main_page).

• При обнаружении ZIM-файла streetzim, созданного с параметром --routing, дополнительно предоставит инструменты plan_driving_route, geocode и route_from_places, чтобы локальный агент мог запросить «проложи маршрут от А до Б» и получить пошаговые инструкции, расстояние и расчетное время.

Принцип проектирования — оппортунистические возможности: начните с одного ZIM-файла Википедии, и вы получите сервер Википедии. Добавьте mdwiki_en_all_*.zim, и он также будет отвечать на медицинские вопросы. Добавьте ZIM-файл streetzim, и он сможет планировать маршруты движения для области, которую покрывает этот ZIM. Инструменты появляются только тогда, когда присутствуют соответствующие данные, поэтому список инструментов агента всегда точно отражает возможности сервера.

Установка

Требуется Python 3.10+.

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

libzim — это нативный wheel-пакет; готовые пакеты существуют для macOS (x86_64/arm64), Linux (x86_64/aarch64, glibc и musl) и Windows x64. На других платформах pip будет выполнять сборку из исходного кода, и вам потребуется набор инструментов C++.

Related MCP server: kiwix-mcp

Запуск

Поместите ваши ZIM-файлы в один каталог и запустите:

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

Добавьте в ~/.config/claude-desktop/claude_desktop_config.json (или эквивалентный файл для вашего MCP-клиента):

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

Инструменты

Всегда доступны:

Доступны только при загрузке ZIM-файла streetzim с данными маршрутизации:

Стоимость/эвристика в маршрутизаторе в точности соответствуют JS-просмотрщику streetzim: edge_cost = distance_m / (speed_kmh / 3.6) и heuristic = haversine / (100/3.6), поэтому результаты идентичны тем, что выдал бы браузерный просмотрщик.

Поддерживаемые ZIM-файлы

Определение типа выполняется во время сканирования и использует комбинацию префикса имени файла, метаданных ZIM (Name / Tags / Creator / Publisher) и сигнатур внутри архива. Из коробки поддерживаются:

• Википедия — любой wikipedia_*.zim (Creator: Wikipedia, тег wikipedia).

• mdwiki — mdwiki_*.zim от WikiProjectMed Foundation (теги mdwiki / medical).

• streetzim — определяется по наличию routing-data/graph.bin или map-config.json внутри архива.

• generic — всё остальное (файл *.zim всё равно будет обслуживаться; применяется только набор инструментов по умолчанию ZimKind.GENERIC).

Пример сессии

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

Мобильные устройства

Честный ответ: запуск нативного Python + libzim на iOS сегодня затруднителен, так как для python-libzim нет wheel-пакетов под iOS, и вам пришлось бы самостоятельно кросс-компилировать C++ библиотеку libzim. Практические варианты в порядке возрастания сложности:

1. LAN-мост (самый простой, работает сейчас). Запустите mcpzim --transport streamable-http --host 0.0.0.0 на машине в вашей сети (или на Raspberry Pi). Укажите на него ваш мобильный агент. Данные ZIM остаются на домашнем сервере; ваш телефон просто видит MCP-эндпоинт с богатыми возможностями. Это работает сегодня без написания мобильного кода.

2. Android через Termux. pkg install python clang && pip install mcpzim в Termux соберет libzim из исходного кода. Запускайте на устройстве, предоставляя доступ через stdio (для локального процесса агента) или streamable-http на localhost для внутриапповых клиентов.

3. Портирование на Swift/Kotlin. Формат маршрутизации SZRG v2 и уровень доступа к ZIM намеренно сделаны простыми. Модуль MCP на Swift, вызывающий C++ libzim через Swift-биндинги (как это уже делает Kiwix для iOS), мог бы предоставить тот же набор инструментов, что и этот Python-сервер. Это лучший путь для iOS-чата, который хочет иметь встроенного MCP-провайдера инструментов.

4. Мост Kiwix-serve. Мобильные приложения Kiwix уже содержат встроенный локальный HTTP-сервер; альтернативный режим mcpzim, который проксирует запросы к http://localhost:port/ вместо прямого открытия ZIM-файлов, будет работать везде, где работает Kiwix. (Пока не реализовано — PR приветствуются.)

Разработка

pip install -e '.[dev]'
pytest

Тесты не требуют реальных ZIM-файлов; тесты маршрутизации создают крошечный граф SZRG v2 в памяти с помощью mcpzim.routing.encode_graph_v2, а библиотечные тесты напрямую проверяют классификатор.

Лицензия

MIT.