openzim-mcp

OpenZIM MCP サーバー

静的な ZIM アーカイブを AI モデル向けの動的なナレッジエンジンに変換します

---

✨ 特長。 スキーマが小さく、小規模モデルでの振り分けにも適した、無駄のない 8 つの高度なツール（zim_query、zim_search、zim_get、zim_get_section、zim_browse、zim_metadata、zim_links、zim_health）を備えています。また、自然言語でクエリできる、ツールが 1 つの シンプルモードも利用できます。アーカイブタイプ別プリセットがソース（Wikipedia、Stack Exchange など）に応じて検索を自動調整し、被リンクの検出で「ここにリンクしているものは何か」に答え、ネイティブの libzim 機能であらゆるアーカイブを検証・調査できます。Smitheryおよび公式 MCP Registryで利用できます。リリースノート → ドキュメント →

OpenZIM MCP は、Wikipedia、Wiktionary、Stack Exchange、その他の Kiwix Libraryに収録されたナレッジアーカイブへ、AI モデルが構造化されたオフラインアクセスを行えるようにする、最新のセキュアで高性能なモデルコンテキストプロトコルサーバーです。ZIM 形式に対応しています。

単なる生テキストのダンプではなく、膨大なナレッジリポジトリにインテリジェントにアクセスする必要がある、リサーチアシスタント、ナレッジチャットボット、コンテンツ分析システム向けに構築されています。名前空間（記事、メタデータ、メディア）によるスマートなナビゲーション、構造を考慮した検索（セクション、目次、関連記事）、候補表示と複数アーカイブ検索に対応した全文検索、コンテンツ間の関係をマッピングするリンクグラフ抽出を利用できます。キャッシュとページネーションに対応した操作で大規模アーカイブでも応答性を保ち、包括的な入力検証とパストラバーサル対策で安全性を確保します。

ストリーミング可能な HTTP トランスポート、ライブ変更通知に対応したエントリーごとの MCP リソース、シンプルモードと高度なモードの両方を標準搭載しています。

インストール

# uv (recommended — isolated CLI tool)
uv tool install openzim-mcp

# pip
pip install openzim-mcp

# Docker (multi-arch image, ghcr.io) — runs as a local stdio MCP server
docker pull ghcr.io/cameronrye/openzim-mcp
docker run -i --rm -v ~/zim-files:/data ghcr.io/cameronrye/openzim-mcp

コンテナのトランスポートはデフォルトで stdio です。そのため、docker run -i は標準入力／標準出力を介して MCP で通信します。バイナリと同じ方法で MCP クライアントに接続してください（クイックスタートを参照）。長時間稼働する HTTP サービス（ベアラー認証、CORS、ヘルスエンドポイント）を利用するには、実行時に -e OPENZIM_MCP_TRANSPORT=http -e OPENZIM_MCP_HOST=0.0.0.0 -e OPENZIM_MCP_AUTH_TOKEN=… -p 8000:8000 を指定します。HTTP と Docker によるデプロイを参照してください。

インストールを確認します。

openzim-mcp --help

最初の ZIM アーカイブを入手する

読み込むアーカイブがなければ、サーバーは何もできません。実際のアーカイブを入手しましょう。openZIM プロジェクト独自のテストスイートから、気候変動に関する英語版 Wikipedia の 13.6 MB の抜粋をダウンロードできます。アカウントもインストールも不要です。

mkdir -p ~/zim-files
curl -fsSL -o ~/zim-files/wikipedia_en_climate_change_mini_2024-06.zim \
  https://raw.githubusercontent.com/openzim/zim-testing-suite/main/data/withns/wikipedia_en_climate_change_mini_2024-06.zim

~/zim-files は、以下のすべての例でサーバーが参照するディレクトリです。サーバー自身が ~ を展開するため、シェルからでもクライアントの設定ファイルからでも同じように使えます。Wikipedia、Wiktionary、Stack Exchange などの完全なアーカイブ（数百 MB から数十 GB まで）については、browse.library.kiwix.org を開き、同じディレクトリに .zim を保存してください。チェックサムや Windows PowerShell での同等の手順を含む詳細は、クイックスタートを参照してください。

Smithery とワンクリックインストール

OpenZIM MCP は Smithery レジストリと公式 MCP レジストリ（io.github.cameronrye/openzim-mcp として）に登録されています。Smithery CLI を使って MCP クライアントに追加できます。

npx @smithery/cli mcp add rye/openzim-mcp --client claude

ワンクリックでインストールできる Claude Desktop 拡張機能を利用するには、最新リリースから openzim-mcp-<version>.mcpb アセット（およびその .sha256）をダウンロードし、ダブルクリックしてください。このバンドルは、バージョンを固定した uvx openzim-mcp@<version> を起動するため、ホストに uv が必要です。また、ZIM ディレクトリの入力を求められます。メンテナー向けの運用手順については、docs/distribution.mdを参照してください。

クイックスタート

Simple モード（デフォルト。自然言語ツール zim_query を 1 つ公開）でサーバーを実行します。

openzim-mcp ~/zim-files

MCP クライアントに接続します。Claude Desktop の claude_desktop_config.json を使った例です（stdio で通信する MCP クライアントなら、どれも同じように動作します）。

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "uvx",
      "args": ["openzim-mcp", "~/zim-files"]
    }
  }
}

クライアントが接続したら、LLM に 「Photosynthesis の記事を要約して」 と尋ねてください。zim_query が適切な基盤ツールに自動的に振り分けます。

すべての機能を使うには、Advanced モードで実行し、8 つの専門ツールをすべて公開します。

{
  "mcpServers": {
    "openzim-mcp-advanced": {
      "command": "uvx",
      "args": ["openzim-mcp", "--mode", "advanced", "~/zim-files"]
    }
  }
}

HTTP トランスポート（ベアラー認証、CORS、ヘルスエンドポイントを備えた長時間稼働サービス）については、HTTP と Docker によるデプロイを参照してください。

特長

• 高度な操作を8つのツールで提供 — zim_query、zim_search、zim_get、zim_get_section、zim_browse、zim_metadata、zim_links、zim_health。22個から削減し、高度なモードのスキーマは約36KBから約24.1KBになり、MCP Taxの問題が生じる領域を脱しています。API リファレンス →
• Streamable HTTP トランスポート — ベアラートークン認証、CORS、ヘルスエンドポイント、マルチアーキテクチャの Docker イメージに対応しています。HTTP と Docker のデプロイ →
• エントリーごとの MCP リソースとサブスクリプション — zim://{name}/entry/{path} をネイティブ MIME タイプで提供します。クライアントが subscriptions/listen ストリームを開くと、ZIM の出現・消失時に resources/list_changed、置き換え時に resources/updated を受信します。リソース、プロンプト、サブスクリプション →
• シンプルモードの zim_query — 自然言語で使える単一のツールが適切な操作を呼び出します。小規模モデルのデプロイ先に合わせて調整されています。クイックスタート →
• アーカイブタイプのプリセット — OpenZIM MCP はアーカイブタイプ（Wikipedia、Stack Exchange など）を検出し、それに応じて検索と要約を自動調整します。たとえば、Stack Exchange のダンプは、投票スコアのノイズがない、読みやすい Q&A 形式で表示されます。TOML ファイル（OPENZIM_MCP_PRESETS_OVERRIDE_PATH）を使って、同梱のデフォルト設定を上書きできます。
• ネイティブ libzim のイントロスペクション — zim_health(zim_file_path=...) はアーカイブの整合性を検証し（Archive.check() + チェックサム）、zim_metadata はアーカイブの識別情報、全文／タイトルインデックスの機能、M/Counter の MIME タイプ内訳を報告します。API リファレンス →
• 被リンクの検出（「ここにリンクしているページ」） — zim_links(direction="inbound") は、エントリーにリンクしているページをリンク元の重要度順に返します。事前にサイドカーを作成する必要があります。openzim-mcp build link-graph <archive>.zim を実行すると、アーカイブと同じ場所に <archive>.zim.linkgraph.sqlite が書き込まれます。API リファレンス →

モード

OpenZIM MCP には2つのモードがあり、クライアントごとにどちらかを選びます。

シンプルモード（デフォルト）では、自然言語のリクエストを解析して適切な内部操作を呼び出す、インテリジェントな単一のツール zim_query を提供します。小規模モデルのデプロイ先向けに構築されており、通信時のデータ量を最小限に抑え、呼び出しの振り分けを LLM のコンテキストではなくサーバー側で行います。特別な理由がなければ、まずはこちらをお試しください。

高度なモードでは、8つの専門ツール（zim_query、zim_search、zim_get、zim_get_section、zim_browse、zim_metadata、zim_links、zim_health）に加え、3つの MCP プロンプト（/research、/summarize、/explore）とエントリーごとのリソースを提供します。スキーマ全体を確実に使い分けられる大規模モデルや、ページネーション、名前空間の閲覧、リンクグラフの抽出を細かく制御したいクライアント向けです。

目安として、パラメーター数が13B以下のモデルにはシンプルモードが適しています。より大規模なモデル（Claude Sonnet／Opus、GPT-4oクラス、Llama 70B以上）では、高度なモードを直接使い分けられます。選び方についてはLLM 統合パターンをご覧ください。

ドキュメント

すべてのドキュメントは https://cameronrye.github.io/openzim-mcp/docs/ にあります。

グループ	ページ
はじめる	はじめに · インストール · クイックスタート · ZIM の概念 · LLM 統合パターン · 実例
概念	スマート検索 · 検索結果の再ランキング · アーキテクチャ概要
リファレンス	API リファレンス · 設定 · リソース、プロンプト、サブスクリプション · CLI リファレンス
運用	HTTP と Docker のデプロイ · パフォーマンスの最適化 · セキュリティのベストプラクティス · トラブルシューティング · FAQ · アップグレード

プロジェクトの状況

現在のリリースは v3.4.0 です（2026-10-25）。 v2.0.0 GA は 2026-05-27 にリリースされました。SECURITY.md に記載のとおり、v1.x のメンテナンス期間は v2.5.0 のリリース（2026-06-18）をもって終了し、現在のメジャー系列で開発を継続しています。v3.0.0 は HTTP サブスクリプションクライアントに対する破壊的変更を含むリリースです。resources/subscribe／unsubscribe は提供されなくなり、ライブ更新は 2026-07-28 のプロトコル改訂で導入された subscriptions/listen を通じて行われます。また、2.x で作成されたリンクグラフのサイドカーは再構築が必要です。ツール、リソース、プロンプトに変更はなく、レガシーハンドシェイクを使用するクライアントは引き続き動作します。詳細は CHANGELOG.md を、手順についてはアップグレードガイドをご覧ください。

コントリビューション

開発環境のセットアップ、テストコマンド、コードスタイル、リリースプロセスについては、CONTRIBUTING.md をご覧ください。

セキュリティ

脆弱性の開示ポリシーについては、SECURITY.md をご覧ください。既知の CVE はありません。

ライセンス

MIT。LICENSE をご覧ください。

謝辞

• ZIM 形式と libzim ライブラリを提供する openZIM および Kiwix
• オープンなクライアント・サーバープロトコルを提供する Model Context Protocol
• オープンソースコミュニティとコントリビューター

---

❤️ を込めて Cameron Rye が作成