Lupa — local file search for your Mac

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

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

One-click editor setup isn’t available for this listing yet — we don’t have a confirmed install command, and we’d rather show nothing than point your editor at the wrong package or host. Follow the project’s own setup instructions, linked above.

Manual Client & Custom JSON ConfigExpand JSON ▾

No confirmed setup config for this listing yet. We only publish a config block when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for Lupa — local file search for your Mac, and we’d rather show nothing than a guess you’d paste into your client. Follow the project’s own setup instructions for the current steps.

Documentation Overview

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.

Code

"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.

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

macOS only.

Install

Claude Code

Terminal

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

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

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`

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

Code

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

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Lupa — local file search for your Mac

We don't have a confirmed install command for Lupa — local file search for your Mac yet, so we don't publish a generated one — a guessed package name would point at the wrong package or none at all. Follow the project's own README or setup instructions (https://github.com/paeyoungpark-web/lupa-mcp) for the current steps.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Lupa — local file search for your Mac AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/lupa-local-file-search-for-your-mac?style=directory)](https://allmcps.com/mcp/lupa-local-file-search-for-your-mac)

HTML Embed

<a href="https://allmcps.com/mcp/lupa-local-file-search-for-your-mac"><img src="https://allmcps.com/api/badge/lupa-local-file-search-for-your-mac?style=directory" alt="Lupa — local file search for your Mac on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Lupa — local file search for your Mac →Install in Claude Desktop Install in Cursor Install in VS Code Setup guides for all 13 MCP clients

Lupa — local file search for your Mac

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

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Manual Client & Custom JSON ConfigExpand JSON ▾

Documentation Overview

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.

Code

"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.

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

macOS only.

Install

Claude Code

Terminal

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

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

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`

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

Code

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

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Lupa — local file search for your Mac

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/lupa-local-file-search-for-your-mac?style=directory)](https://allmcps.com/mcp/lupa-local-file-search-for-your-mac)

HTML Embed

<a href="https://allmcps.com/mcp/lupa-local-file-search-for-your-mac"><img src="https://allmcps.com/api/badge/lupa-local-file-search-for-your-mac?style=directory" alt="Lupa — local file search for your Mac on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.