mcpzim

로컬 LLM 에이전트가 오프라인 ZIM 파일 그룹을 사용할 수 있도록 하는 MCP 서버입니다. ZIM 디렉토리를 지정하면 서버는 다음을 수행합니다:

• 무엇이 있는지 인벤토리를 작성(list_libraries)하고 로드된 항목에 따라 집계된 기능(일반 지식, 의학 지식, 지도/경로 탐색)을 광고합니다.

• 모든 ZIM에 걸쳐 검색 및 문서 검색 기능을 노출합니다(search, get_article, get_main_page).

• --routing으로 빌드된 streetzim ZIM을 감지하면 plan_driving_route, geocode, route_from_places를 추가로 노출하여 로컬 에이전트가 *"A에서 B까지의 주행 경로를 알려줘"*라고 요청하고 거리별 방향, 거리, 예상 시간을 얻을 수 있도록 합니다.

설계 원칙은 **기회주의적 기능(opportunistic capability)**입니다. Wikipedia ZIM 하나로 시작하면 Wikipedia 서버가 됩니다. mdwiki_en_all_*.zim을 넣으면 의학 질문에도 답변합니다. streetzim ZIM을 넣으면 해당 ZIM이 다루는 지역의 주행 경로도 계획할 수 있습니다. 도구는 기본 데이터가 존재할 때만 나타나므로 에이전트의 도구 목록은 서버가 할 수 있는 일에 대해 거짓말을 하지 않습니다.

설치

Python 3.10+가 필요합니다.

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

libzim은 네이티브 휠입니다. 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" }
    }
  }
}

도구

항상 사용 가능:

경로 데이터가 포함된 streetzim ZIM이 로드된 경우에만 표시:

라우터의 비용/휴리스틱은 streetzim의 JS 뷰어와 정확히 일치합니다: edge_cost = distance_m / (speed_kmh / 3.6) 및 heuristic = haversine / (100/3.6)이므로 결과는 브라우저 내 뷰어가 생성하는 것과 동일합니다.

지원되는 ZIM

유형 감지는 스캔 시 실행되며 파일 이름 접두사, ZIM의 Name / Tags / Creator / Publisher 메타데이터 및 아카이브 내부의 서명 항목 조합을 사용합니다. 기본 지원:

• Wikipedia — 모든 wikipedia_*.zim (Creator: Wikipedia, wikipedia 태그 지정).

• mdwiki — WikiProjectMed Foundation의 mdwiki_*.zim (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 휠이 없고 C++ libzim을 직접 교차 컴파일해야 하기 때문에 현재 iOS에서 네이티브 Python + libzim을 실행하는 것은 고통스럽습니다. 노력 순서에 따른 실용적인 옵션:

1. LAN 브리지 (가장 쉽고 지금 바로 가능). 네트워크(또는 Raspberry Pi)의 머신에서 mcpzim --transport streamable-http --host 0.0.0.0을 실행하세요. 모바일 에이전트를 해당 주소로 지정하세요. ZIM 데이터는 홈 서버에 유지되며 휴대폰은 기능이 풍부한 MCP 엔드포인트를 보기만 하면 됩니다. 모바일 코드가 없어도 지금 바로 작동합니다.

2. Termux를 통한 Android. Termux에서 pkg install python clang && pip install mcpzim을 실행하면 소스에서 libzim이 빌드됩니다. 기기에서 실행하고 stdio(로컬 에이전트 프로세스용) 또는 인앱 클라이언트를 위해 localhost에서 streamable-http를 통해 노출하세요.

3. Swift/Kotlin 포트. SZRG v2 라우팅 형식과 ZIM 액세스 계층은 모두 의도적으로 간단합니다. (Kiwix iOS가 이미 수행하는 것처럼) Swift 바인딩을 통해 C++ libzim을 호출하는 Swift MCP 모듈은 이 Python 서버와 동일한 도구 인터페이스를 노출할 수 있습니다. 이는 인프로세스 MCP 도구 제공자를 원하는 iOS 채팅 앱을 위한 최선의 경로입니다.

4. Kiwix-serve 브리지. Kiwix 모바일 앱은 이미 로컬 HTTP 서버를 내장하고 있습니다. ZIM을 직접 여는 대신 http://localhost:port/로 프록시하는 대체 mcpzim 모드는 Kiwix가 실행되는 곳이면 어디서나 작동할 것입니다. (아직 구현되지 않음 — PR 환영.)

개발

pip install -e '.[dev]'
pytest

테스트는 실제 ZIM 파일이 필요하지 않습니다. 라우팅 테스트는 mcpzim.routing.encode_graph_v2를 사용하여 메모리 내에서 작은 SZRG v2 그래프를 빌드하고, 라이브러리 테스트는 분류기를 직접 실행합니다.

라이선스

MIT.