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

	find / grep / mdfind	lupa-mcp
Searches inside PDF, DOCX, HWP	no	yes
Scanned documents (OCR)	no	yes
Korean partial words and particles	poorly	yes — 보호정책 finds 정보보호정책서.hwp
Speed on a large disk	seconds	~30 ms (indexed)
Agent needs file system access	yes	no — Lupa reads the files, not your agent

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

argument	default	meaning
query	—	see syntax below
limit	10	results to return (max 50)
names_only	false	file names only, ignore contents (faster)
snippet_chars	160	truncate each snippet (0 = none)

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.

argument	default	meaning
path	—	absolute path, as returned by lupa_search
max_chars	8000	cap the returned text (0 = no limit)

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.

Audit log

Every tool call is recorded on your Mac so you can see what an agent searched for and which files it was shown:

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

Each line has the time, the calling client (e.g. Claude Code, Cursor), the tool, the query or path, the paths returned, and whether it succeeded. Snippets and document text are not logged. The file is readable only by you (0600) and never leaves the Mac.

Lines are hash-chained: each entry includes the hash of the previous one, so editing or removing a line is detected. This makes the log tamper-evident, not tamper-proof — deleting the whole file and starting over is still possible.

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

Turn it off with LUPA_MCP_AUDIT=off, or move it with LUPA_MCP_AUDIT_PATH=/path/to/file.jsonl.

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

message	fix
"Lupa를 찾을 수 없습니다" / not found	Install Lupa from the Mac App Store
"검색 인덱스가 없습니다"	Open Lupa, add folders, wait for indexing
"본문 읽기를 지원하지 않습니다"	Update Lupa to 2.0 or later
No results for a file you know exists	Its folder may not be registered in Lupa

License

MIT