Lupa — local file search for your Mac
Lets agents search a Mac's files by name and by text inside documents via the Lupa app
- Pricing
- Free
- Platforms
- macOS, Windows, CLI
- Runs
- Locally
- Version
- 0.3.1
- Listing updated
- 3 days ago
About Lupa — local file search for your Mac
Lupa — local file search for your Mac is a free MCP server for files and documents. It runs locally on your machine and is started by your AI client.
This server reads the local index built by Lupa, a macOS file search app, so an agent gets document contents without being given access to the disk. Searches run in about 30 ms entirely on the Mac with no network use, and cover PDF, Word, Excel, PowerPoint, plain text, Korean HWP and HWPX, and scanned PDFs read with OCR. Korean partial words and attached particles match, which the README contrasts with Spotlight.
There are two tools: lupa_search returns ranked paths with snippets, and lupa_read returns the text Lupa already extracted from a file, up to a character cap, which also works for formats an agent cannot parse. The query syntax supports name-only and content-only prefixes, folder filters, exclusions, exact phrases, wildcards, kind, size and date filters.
It must be installed through MCP rather than by shelling out to the command-line tool, because sandboxed agent shells such as Aside and Codex kill the App Store-signed binary with exit code 133 or 134. Lupa must be installed, with folders registered and indexed first. Every call is logged on your Mac so you can review what an agent searched. A Windows version of the app bundles its own MCP server, though without HWP body text or scanned-PDF OCR.
Install
Run in a terminal
claude mcp add lupa-mcp -- npx -y lupa-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"lupa-mcp": {
"command": "npx",
"args": [
"-y",
"lupa-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"lupa-mcp": {
"command": "npx",
"args": [
"-y",
"lupa-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"lupa-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"lupa-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"lupa-mcp": {
"command": "npx",
"args": [
"-y",
"lupa-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"lupa-mcp": {
"command": "npx",
"args": [
"-y",
"lupa-mcp"
]
}
}
}Tools this server provides (2)
Taken from the project documentation; the running server may differ.
- lupa_search
- Searches file names and document contents and returns ranked paths with snippets.
- lupa_read
- Returns the indexed text of a file without opening it.
What it does
- Content search
- Finds files by name and by text inside documents, including HWP and OCR'd scanned PDFs.
- Read without opening
- lupa_read returns the indexed text of a file so agents can summarise formats they cannot parse.
- Korean-aware matching
- Matches partial words inside compounds and attached particles.
- Rich query syntax
- Supports name, content and folder prefixes, phrases, wildcards, and kind, size and date filters.
- No disk access for agents
- The agent receives only indexed text from folders you registered.
- Local audit log
- Each tool call is recorded in a log file on the Mac.
Good for
- Find the contract that mentions a penalty clause
- Summarise a Korean HWP document an agent cannot open
- Search an Obsidian vault or synced cloud folder by content
- Look for large presentations modified this week
- Keep agent file lookups local without granting disk permissions
Pricing
Free
Lupa is free in the Mac App Store; no API key or account
Prices change. Check lupa.kr before you buy.
Lupa — local file search for your Mac FAQ
Do I need the Lupa app?
Yes. The server reads the index Lupa builds, so install Lupa, add folders and let indexing finish first.
How do I add it to Claude Code?
Run claude mcp add lupa -- npx -y lupa-mcp. Claude Desktop needs a login-shell wrapper because GUI apps do not inherit PATH.
Why does the command-line tool fail in my agent?
Sandboxed shells block the App Store-signed binary with exit code 133 or 134, so register the MCP server instead.
Does anything leave my computer?
The site says it uses no network and that agents receive only text Lupa has already indexed from registered folders.
Is Lupa — local file search for your Mac free?
Yes. Lupa — local file search for your Mac is free to use.
How do I add Lupa — local file search for your Mac to Claude Code?
Run this command in your terminal: claude mcp add lupa-mcp -- npx -y lupa-mcp
What are the best alternatives to Lupa — local file search for your Mac?
The closest alternatives to Lupa — local file search for your Mac are Ha MCP, Concord MCP, note1, ASTra and CalderFlow.
Alternatives to Lupa — local file search for your Mac

Ha MCP
MCP serverMCP server for managing and automating Home Assistant from AI assistants
Runs locally- 8 tools
- Open source
- 7.9K GitHub stars
- Productivity

Concord MCP
MCP serverLocal-first MCP server for messaging and shared work-state between coding agents
Runs locally- Freemium
- 1.3K GitHub stars
- Developer tools

note1
MCP serverMCP server giving AI assistants search and summaries across your note1 meetings
- 4 tools
- Remote
- Free trial
- 1 GitHub star
- Productivity

ASTra
MCP serverLet agents read, edit, validate and undo Word .docx files with exact operations
Runs locally- 5 tools
- Freemium
- Files and documents

CalderFlow
MCP serverTurn notes or specs into editable flowcharts, timelines and funnels from an AI assistant
- 10 tools
- Remote
- Free
- Design and media

CARTESIAN ECU
MCP serverCheck and repair ECU and TCU flash-file checksums from Claude (Ultimate plan)
Not checked yet- 5 tools
- Remote
- Paid
- Files and documents