lupa-mcp

让你的 AI 智能体按 Mac 上文档的内部内容搜索文档。

一个面向 Lupa 的 MCP 服务器。Lupa 是一款自带索引的 macOS 文件搜索应用。 你的智能体向 Lupa 提问；Lupa 从本地索引返回结果，约 30 毫秒。整个过程不会接触网络。

"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、纯文本、 Hangul HWP/HWPX，以及通过 OCR 识别的扫描版 PDF。

为什么用这个而不是 find/grep

最后一行才是关键。你的智能体可以获取文档内容，而不需要你授权它访问你的磁盘。

Related MCP server: LocalSynapse

环境要求

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

1. 从 Mac App Store 免费安装 Lupa：https://lupa.kr

2. 打开 Lupa，添加你想搜索的文件夹，并等待索引完成。

仅限 macOS。

安装

Claude Code

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

Claude Desktop / Cursor / 任意 MCP 客户端 —— 在客户端的 MCP 配置中添加：

{
  "mcpServers": {
    "lupa": { "command": "npx", "args": ["-y", "lupa-mcp"] }
  }
}

就这样。无需 API 密钥、无需账号、无需配置。

工具

lupa_search

lupa_read

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

查询语法

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 上本机运行。Lupa 没有任何网络代码，本服务器只是启动 Lupa 附带的命令行工具，并把结果传给您的智能体。不会上传任何内容，也没有任何遥测。

说明

• Lupa 的免费索引最多覆盖 50,000 个文件。本服务器继承应用已索引的所有内容 —— 这里没有额外的限制或付费门槛。

• 每个文档只有开头部分会被索引，因此 lupa_read 截断长时间文件时会照作全文截断。

• 如果 Lupa 安装在特殊位置，请将 LUPA_SEARCH_PATH 设置为应用包内的 lupa-search 可执行文件。

故障排除

许可协议

MIT