Lupa — local file search for your Mac

io.github.under71Published by GitHub account under71v0.3.1Updated Oct 25, 2026

Search your Mac's files by name and by text inside documents. Local index, Korean-aware.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & Memory

Overview

AI-generated overview

A macOS-only MCP server that lets an assistant search the files indexed by the Lupa app by name and by text inside documents, and read extracted document text.

What you can do
Search indexed Mac files by file name, document content, folder path, extension, kind, size or date, with ranked paths and matching snippets, and limit results or return names only for speed. Read the text Lupa already extracted from a file, without opening the original, including formats the assistant cannot parse. Use query prefixes for name-only, content-only, folder, exclusion, exact phrase, wildcard, kind, size and date filters, with Korean and Chinese prefix variants.
When to use it
Useful when an assistant needs to find documents on a Mac by what is written inside them, such as PDFs, Word, Excel, PowerPoint, Hangul HWP/HWPX or scanned PDFs read with OCR, without being granted direct disk access. Also handy for Korean-language partial-word and particle matching that Spotlight handles poorly.
Requirements
macOS only. The Lupa app must be installed from the Mac App Store, with folders added and indexing finished; the server reads Lupa's index and does not index itself. Runs locally via npx (Node.js). No API key or account. Lupa 2.0 or later is needed for reading document text. Optional environment variables LUPA_SEARCH_PATH, LUPA_MCP_AUDIT and LUPA_MCP_AUDIT_PATH.
Before you install
The assistant can read the contents of any document in the folders indexed by Lupa, so choose those folders carefully. Every tool call is written to a local audit log by default, recording the client, tool, query or path and returned paths, but not snippets or document text; it can be turned off with LUPA_MCP_AUDIT=off. The log is tamper-evident, not tamper-proof. The free index covers up to 50,000 files, and only the beginning of each document is indexed, so long files are truncated.

Installation

In SourceWeft

  1. Open Lupa — local file search for your Mac in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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 / mdfindlupa-mcp
Searches inside PDF, DOCX, HWPnoyes
Scanned documents (OCR)noyes
Korean partial words and particlespoorlyyes — 보호정책 finds 정보보호정책서.hwp
Speed on a large diskseconds~30 ms (indexed)
Agent needs file system accessyesno — 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

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

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

json
{  "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

argumentdefaultmeaning
query—see syntax below
limit10results to return (max 50)
names_onlyfalsefile names only, ignore contents (faster)
snippet_chars160truncate 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.

argumentdefaultmeaning
path—absolute path, as returned by lupa_search
max_chars8000cap the returned text (0 = no limit)

Query syntax

word1 word2      files matching ALL words rank firstn: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 / wildcardkind:document    document · pdf · hwp · image · video · audio · code · archive · appsize:>10mb       size:<1mbdate: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.

bash
npx lupa-mcp audit            # last 20 callsnpx lupa-mcp audit -n 100npx 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

messagefix
"Lupa를 찾을 수 없습니다" / not foundInstall 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 existsIts folder may not be registered in Lupa

License

MIT

Source: README.md at commit 6e3d8db

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package did not install.

Version history

1
  1. v0.3.1LatestOct 25, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts