lupa-mcp

Let your AI agent search the documents on your Mac — by what's written inside them.

An MCP server for Lupa, a macOS file search app with its own index. Your agent asks Lupa; Lupa answers from a local index in ~30 ms. Nothing touches the network.

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

Searches file names and document contents: PDF, Word, Excel, PowerPoint, plain text, Hangul HWP/HWPX, and scanned PDFs read with OCR.

Why this instead of find/grep

That last row is the point. Your agent gets document contents without you granting it access to your disk.

Requirements

The Lupa app must be installed — this server reads the index that Lupa builds; it does not index anything itself.

1. Install Lupa (free) from the Mac App Store: https://lupa.kr
2. Open it, add the folders you want searchable, and let indexing finish.

macOS only.

Install

Claude Code

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

Claude Desktop / Cursor / any MCP client — add to the client's MCP config:

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

That's it. No API key, no account, no configuration.

Why /bin/zsh -lc? GUI apps don't inherit your shell's PATH, so a bare "command": "npx" fails to start with env: npx: No such file or directory (measured on Claude Desktop and Aside). A login shell finds npx wherever it lives — Homebrew, nvm, or a system install. In a terminal-based client (Claude Code, Codex) plain npx -y lupa-mcp is fine.

Agents: don't run lupa-search through your shell. Sandboxed agent shells (Aside, Codex) kill the App Store-signed CLI at launch — exit code 133 or 134. Register this MCP server instead; it starts outside that sandbox. Full guide: https://lupa.kr/agents.html

Tools

lupa_search

lupa_read

Returns the text Lupa already extracted from a file — cheaper than reading the original, and it works for formats your agent cannot parse. Requires Lupa 2.0 or later.

Query syntax

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

Korean and Chinese prefixes work too (종류: 크기: 날짜: / 种类: 大小: 日期:).

Korean is handled properly — partial words inside compounds and attached particles both match, which is what Spotlight gets wrong.

Privacy

Everything runs on your Mac. Lupa has no network code at all, and this server only launches Lupa's bundled command-line tool and passes the results to your agent. Nothing is uploaded, and there is no telemetry.

Notes

• Lupa's free index covers up to 50,000 files. This server inherits whatever the app indexed — there is no separate limit or paywall here.
• Only the beginning of each document is indexed, so lupa_read truncates long files.
• If Lupa is installed somewhere unusual, set LUPA_SEARCH_PATH to the lupa-search binary inside the app bundle.

Troubleshooting

License

MIT