Lupa — local file search for your Mac

lupa-mcp

让你的 AI Agent 根据文档内容搜索 Mac 上的文件。

适用于 Lupa 的 MCP 服务。Lupa 是一款 macOS 文件搜索应用，拥有自己的索引。 你的 Agent 向 Lupa 发起查询；Lupa 从本地索引中返回结果，耗时约 30 ms。所有操作都不会触及网络。

"find the contract that mentions the penalty clause"
        ↓
   lupa_search  →  ranked paths + matching snippets
   lupa_read    →  the document's text, without opening the file

可搜索文件名和文档内容：PDF、Word、Excel、PowerPoint、纯文本、韩文 HWP/HWPX，以及使用 OCR 读取的扫描版 PDF。

为什么不直接用 find/grep

	find / grep / mdfind	lupa-mcp
搜索 PDF、DOCX、HWP 内的内容	不可以	可以
扫描文档（OCR）	不可以	可以
韩语词语片段和助词	效果不佳	可以 — 보호정책 可以找到 정보보호정책서.hwp
在大型磁盘上的速度	数秒	约 30 ms（已建立索引）
Agent 需要访问文件系统	需要	不需要 — Lupa 读取文件，而不是你的 Agent

最后一行才是重点。你的 Agent 可以获取文档内容，而无需你授予它访问磁盘的权限。

要求

必须安装 Lupa 应用 — 此服务读取 Lupa 建立的索引；它本身不会为任何内容建立索引。

1. 从 Mac App Store 免费安装 Lupa：https://lupa.kr
2. 打开应用，添加要搜索的文件夹，并等待索引完成。

仅支持 macOS。

安装

Claude Code

claude mcp add lupa -- npx -y lupa-mcp

Claude Desktop / Cursor / 任意 MCP 客户端 — 将以下内容添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "lupa": { "command": "/bin/zsh", "args": ["-lc", "npx -y lupa-mcp"] }
  }
}

就这么简单。无需 API 密钥、账号或配置。

为什么使用 /bin/zsh -lc？ GUI 应用不会继承 shell 的 PATH，因此直接使用 "command": "npx" 会因 env: npx: No such file or directory 而无法启动 （在 Claude Desktop 和 Aside 上测得）。登录 shell 能在任何位置找到 npx — 无论它由 Homebrew、nvm 安装，还是通过系统安装。在基于终端的客户端（Claude Code、Codex）中， 直接使用 npx -y lupa-mcp 即可。

Agent：不要通过 shell 运行 lupa-search。 沙盒化的 Agent shell （Aside、Codex）会在启动时终止由 App Store 签名的 CLI — 退出代码为 133 或 134。 请改为注册此 MCP 服务；它会在沙盒之外启动。 完整指南：https://lupa.kr/agents.html

工具

lupa_search

参数	默认值	含义
query	—	语法见下文
limit	10	返回的结果数量（最多 50）
names_only	false	仅搜索文件名，忽略内容（更快）
snippet_chars	160	截断每条摘要（0 = 不截断）

lupa_read

返回 Lupa 已从文件中提取的文本 — 比读取原始文件更省资源，而且适用于 Agent 无法解析的格式。需要 Lupa 2.0 或更高版本。

参数	默认值	含义
path	—	绝对路径，由 lupa_search 返回
max_chars	8000	返回文本的上限（0 = 不限）

查询语法

word1 word2      files matching ALL words rank first
n:word           file name only          (name:, 이름:, 文件名:)
c:word           document content only   (content:, 내용:, 内容:)
f:word           folder path contains    (폴더:, 文件夹:)
-word            exclude
"exact phrase"   literal match
.pdf  *.mp3  report*      extension / wildcard
kind:document    document · pdf · hwp · image · video · audio · code · archive · app
size:>10mb       size:<1mb
date:today       date:week · date:month · date:7d · date:2026-06

韩语和中文前缀也可使用（종류: 크기: 날짜: / 种类: 大小: 日期:）。

韩语处理得当 — 复合词中的词语片段以及附加的助词都能匹配，这是 Spotlight 做不到的。

审计日志

每次工具调用都会记录在你的 Mac 上，因此你可以查看 Agent 搜索了什么，以及它看到了哪些文件：

~/Library/Logs/Lupa/mcp-audit.jsonl

每行包含时间、调用客户端（例如 Claude Code、Cursor）、工具、查询或路径、返回的路径，以及操作是否成功。**摘要和文档文本不会记录。**该文件仅你本人可读（0600），且永远不会离开 Mac。

日志各行通过哈希链相连：每条记录都包含上一条记录的哈希，因此修改或删除行都会被检测到。这使日志具备防篡改检测能力，而非绝对防篡改 — 仍然可以删除整个文件并重新开始。

npx lupa-mcp audit            # last 20 calls
npx lupa-mcp audit -n 100
npx lupa-mcp audit --verify   # exit 0 if the chain is intact, 1 if a line was changed or removed

设置 LUPA_MCP_AUDIT=off 可关闭日志，或通过 LUPA_MCP_AUDIT_PATH=/path/to/file.jsonl 更改日志位置。

隐私

所有操作都在你的 Mac 上运行。Lupa 完全没有网络代码，此服务只会启动 Lupa 自带的命令行工具，并将结果传递给你的 Agent。不会上传任何内容，也不会收集遥测数据。

注意事项

• Lupa 的免费索引最多覆盖 50,000 个文件。此服务会沿用应用已建立索引的内容——这里没有单独的限制或付费墙。
• 只会对每个文档的开头部分建立索引，因此 lupa_read 会截断较长的文件。
• 如果 Lupa 安装在不常见的位置，请将 LUPA_SEARCH_PATH 设置为应用程序包内的 lupa-search 二进制文件。

故障排除

提示信息	解决方法
"Lupa를 찾을 수 없습니다" / 未找到	从 Mac App Store 安装 Lupa
"검색 인덱스가 없습니다"	打开 Lupa，添加文件夹，然后等待建立索引
"본문 읽기를 지원하지 않습니다"	将 Lupa 更新至 2.0 或更高版本
找不到已知存在的文件	该文件所在的文件夹可能尚未在 Lupa 中注册

许可证

MIT