officegrep

officegrep

エージェント向けの、Word、PowerPoint、Excel、PDF 内の全文検索ツールです。

grep では .docx 内の文字を一文字も確認できません。officegrep はテキストを抽出し、1 つの SQLite ファイルにインデックスを作成して、MCP 経由であらゆるエージェントに提供します。

$ officegrep search "bending moment"

Found 3 hits:

F:\reports\pole-design.docx  [table p 89]
  design bending moment (load point 0.25 m from tip); deflection limit; test moment = 2× …

F:\notes\composites.md  [line 32]
  … utilization 81%. **test bending moment = 2× the standard test moment** …

中国語版：README.zh-CN.md

理由

• grep / ripgrep が読み取れるのはプレーンテキストだけです。.docx は XML の ZIP ファイルで、.xlsx は共有テーブルに文字列を保存し、.pdf は圧縮ストリームです。
• 一般的な RAG では、埋め込みサービス、ベクトルストア、ネットワーク経由の往復が必要です。
• 必要なのは SQLite ファイル 1 つだけです。オフラインで、増分更新に対応し、処理は数ミリ秒です。

インストール

# one command, no clone, no uv
pip install https://github.com/Asgoresmilelong/officegrep/releases/download/v0.1.1/officegrep-0.1.1-py3-none-any.whl

# or from source
pip install git+https://github.com/Asgoresmilelong/officegrep

実行時の依存関係：lxml、openpyxl。PDF サポートを利用するには、オプションの pypdf を追加します。

公式の MCP レジストリ には io.github.Asgoresmilelong/officegrep として登録されています。また、バンドルをインストールする MCP ホスト向けに、リリースページ から .mcpb バンドルも入手できます（uv が必要です）。

CLI

officegrep index ~/Documents ~/Downloads     # build / update (incremental)
officegrep search "island reef" --limit 5
officegrep search "wind load" --under ~/Documents
officegrep stats

インデックスは ~/.officegrep/index.db に保存されます。--db または OFFICEGREP_DB で保存先を変更できます。

初回実行

特別な操作は必要ありません。officegrep mcp の起動時にインデックスが空の場合、エージェントとの会話が続く間に、バックグラウンドで ~/Documents、~/Downloads、~/Desktop をスキャンします（ファイルあたりの上限は 25 MB）。その間に行われた search_docs 呼び出しには、誤解を招く「結果なし」ではなく、「インデックス作成中」というメモが返されます。

• 自動インデックス作成を無効にする：OFFICEGREP_AUTOINDEX=0
• 別のフォルダーをスキャンする：OFFICEGREP_ROOTS="~/work;~/papers"

同期を維持する

officegrep watch ~/Documents           # re-index on change: 2s poll, no extra dependency
officegrep watch ~/Documents --once    # single sync pass (cron / CI friendly)

または、MCP サーバーにバックグラウンドで監視させることもできます。

OFFICEGREP_WATCH="~/Documents;~/Downloads" officegrep mcp

インデックスは WAL モードで動作するため、watch プロセスと MCP サーバーは 1 つのデータベースファイルを同時に共有できます。デフォルトのロールバックジャーナルでは database is locked エラーが発生します。

MCP サーバー

officegrep mcp

クライアント設定（Claude Desktop / Cursor / Codex / あらゆる MCP ホスト）：

{
  "mcpServers": {
    "officegrep": {
      "command": "officegrep",
      "args": ["mcp", "--db", "/Users/me/.officegrep/index.db"]
    }
  }
}

ツール	機能
search_docs	全文検索 → ファイルパス、位置情報（p 42、slide 3、Sheet1!12、page 7）、ハイライト付きスニペット
list_docs	インデックス済みファイルとブロック数の一覧
index_folder	インデックスを作成／更新（増分）

プロトコルには、stdio 上で手書きの JSON-RPC を使用しており、MCP SDK への依存はありません。

仕組み

docx / pptx  →  zipfile + lxml, read the XML directly
xlsx         →  openpyxl (read_only)
pdf          →  pypdf (optional)
txt / md     →  line chunks, line numbers kept

• すべてのブロックには人が読める位置情報が付いています。エージェントが最初に尋ねるのは「どこ？」だからです。
• インデックスには SQLite の FTS5 と trigram トークナイザーを使用しています。単語分割器なしで CJK とラテン文字の両方に対する部分一致検索ができ、bm25() で順位付けします。
• 1～2 文字のクエリはトライグラムに一致しないため、ヒット数で順位付けしたスキャンに切り替わります（CJK のクエリは 2 文字であることがよくあります）。
• 増分更新では、まず (size, mtime) を比較し、値が異なる場合にのみ SHA-1 でハッシュを計算します。

実際のエンジニアリング文書コーパスでのベンチマーク：

指標	値
ファイル数	43（docx / pptx / xlsx / md、8.6 MB の資料を含む）
テキストブロック数	2,260
初回インデックス作成	2.16 s
データベース	1.9 MiB

制限事項

• OCR はありません。スキャンした PDF からは何も取得できません。
• 意味検索ではなく、文字列検索です。「tower」を検索しても、「pole」が両方に含まれていない限り見つかりません。
• 1～2 文字のクエリはテーブルをスキャンするため、数十万ブロックを超えると遅くなります。
• インデックスの対象は本文のみです。コメント、変更履歴、ヘッダー、フッターは対象外です。

ライセンス

MIT