로컬 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: ZimAgent
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에 대한 전체 텍스트 검색(존재하는 경우 libzim의 Xapian 인덱스를 사용하고, 그렇지 않으면 제목 접두사 제안으로 대체). 선택적 |
| 경로별로 항목을 가져옵니다. HTML에서 navbox / infobox / 스크립트 찌꺼기가 제거되어 LLM이 깔끔한 텍스트를 볼 수 있습니다. |
| 하나의 ZIM 또는 로드된 모든 ZIM의 메인 페이지를 가져옵니다. |
경로 데이터가 포함된 streetzim ZIM이 로드된 경우에만 표시:
도구 | 기능 |
| streetzim 라우팅 그래프에 대한 A* 알고리즘. 입력: 두 개의 |
| streetzim의 접두사 청크 검색 인덱스를 사용하여 장소/주소 문자열을 좌표로 확인합니다. |
| 편의 기능: 두 끝점을 지오코딩한 다음 경로를 계획합니다. |
라우터의 비용/휴리스틱은 streetzim의 JS 뷰어와 정확히 일치합니다: edge_cost = distance_m / (speed_kmh / 3.6) 및 heuristic = haversine / (100/3.6)이므로 결과는 브라우저 내 뷰어가 생성하는 것과 동일합니다.
유형 감지는 스캔 시 실행되며 파일 이름 접두사, 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을 실행하는 것은 고통스럽습니다. 노력 순서에 따른 실용적인 옵션:
LAN 브리지 (가장 쉽고 지금 바로 가능). 네트워크(또는 Raspberry Pi)의 머신에서 mcpzim --transport streamable-http --host 0.0.0.0을 실행하세요. 모바일 에이전트를 해당 주소로 지정하세요. ZIM 데이터는 홈 서버에 유지되며 휴대폰은 기능이 풍부한 MCP 엔드포인트를 보기만 하면 됩니다. 모바일 코드가 없어도 지금 바로 작동합니다.
Termux를 통한 Android. Termux에서 pkg install python clang && pip install mcpzim을 실행하면 소스에서 libzim이 빌드됩니다. 기기에서 실행하고 stdio(로컬 에이전트 프로세스용) 또는 인앱 클라이언트를 위해 localhost에서 streamable-http를 통해 노출하세요.
Swift/Kotlin 포트. SZRG v2 라우팅 형식과 ZIM 액세스 계층은 모두 의도적으로 간단합니다. (Kiwix iOS가 이미 수행하는 것처럼) Swift 바인딩을 통해 C++ libzim을 호출하는 Swift MCP 모듈은 이 Python 서버와 동일한 도구 인터페이스를 노출할 수 있습니다. 이는 인프로세스 MCP 도구 제공자를 원하는 iOS 채팅 앱을 위한 최선의 경로입니다.
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.
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.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
