officegrep

officegrep

为 Agent 搜索 Word、PowerPoint、Excel 和 PDF 中的全文。

grep 看不到 .docx 文件中的任何字符。officegrep 会提取文本，将其编入一个 SQLite 文件的索引，并通过 MCP 提供给任何 Agent。

$ 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

为什么选择 officegrep

• grep / ripgrep 只能读取纯文本。.docx 是由 XML 文件组成的 zip，.xlsx 将字符串保存在共享表中，.pdf 则是压缩流。
• 通用 RAG 需要嵌入服务、向量存储和网络往返。
• 这里只需要一个 SQLite 文件：离线、增量更新，耗时仅为毫秒级。

安装

# 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 Registry 中列为 io.github.Asgoresmilelong/officegrep；releases page 上也提供了 .mcpb 包，供安装此类软件包的 MCP 主机使用（需要 uv）。

命令行

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），同时 Agent 可以继续交互；在此期间发出的 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 服务可以同时使用同一个数据库文件；若使用默认的回滚日志模式，则会出现 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

• 每个文本块都带有易于阅读的定位信息，因为 Agent 首先会问“在哪里？”。
• 索引使用 SQLite FTS5 和 trigram 分词器：支持中日韩文字和拉丁文字的子串匹配，无需词语切分器，并按 bm25() 排序。
• 1–2 个字符的查询无法匹配三元组，因此会改为扫描并按命中次数排序（中日韩文字查询经常只有两个字符）。
• 增量更新：先比较 (size, mtime)，仅在两者不同时才使用 SHA-1 进行哈希计算。

在真实工程文档语料库上的基准测试：

指标	数值
文件	43 个（docx / pptx / xlsx / md，含一个 8.6 MB 的演示文稿）
文本块	2,260
首次建立索引	2.16 秒
数据库	1.9 MiB

限制

• 不支持 OCR：扫描版 PDF 不会产生任何结果。
• 仅支持字面搜索，不支持语义搜索——除非“tower”和“pole”都出现，否则搜索“tower”不会找到“pole”。
• 1–2 个字符的查询会扫描整张表；块数量达到几十万后速度会变慢。
• 仅为正文编制索引：不包括评论、修订记录、页眉或页脚。

许可证

MIT