Lupa — local file search for your Mac

lupa-mcp

Mac 上のドキュメントを、書かれている内容から AI エージェントが検索できます。

独自のインデックスを持つ macOS 用ファイル検索アプリ、Lupa の MCP サーバーです。 エージェントが Lupa に問い合わせると、Lupa はローカルのインデックスから約 30 ms で回答します。ネットワークに接続することはありません。

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

ファイル名とドキュメントの内容を検索します。PDF、Word、Excel、PowerPoint、プレーンテキスト、 Hangul HWP/HWPX、および OCR で読み取ったスキャン済み PDF に対応しています。

find/grep ではなく、これを使う理由

	find / grep / mdfind	lupa-mcp
PDF、DOCX、HWP の内容を検索	いいえ	はい
スキャン済みドキュメント（OCR）	いいえ	はい
韓国語の部分的な単語と助詞	苦手	はい — 보호정책 で 정보보호정책서.hwp が見つかります
大容量ディスクでの速度	数秒	約 30 ms（インデックス済み）
エージェントにファイルシステムへのアクセスが必要	はい	いいえ — ファイルを読むのは Lupa であり、エージェントではありません

最後の行が重要です。ディスクへのアクセスを許可することなく、エージェントにドキュメントの内容を渡せます。

必要条件

Lupa アプリのインストールが必要です — このサーバーは Lupa が作成したインデックスを読み取り、自身でインデックスを作成することはありません。

1. Mac App Store から Lupa を無料でインストールします：https://lupa.kr
2. アプリを開き、検索対象にするフォルダーを追加して、インデックス作成が終わるまで待ちます。

macOS のみ対応しています。

インストール

Claude Code

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

Claude Desktop / Cursor / その他の MCP クライアント — クライアントの MCP 設定に追加します：

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

これだけです。API キーもアカウントも設定も必要ありません。

なぜ /bin/zsh -lc なのですか？ GUI アプリはシェルの PATH を引き継がないため、"command": "npx" だけでは起動時に env: npx: No such file or directory が発生します（Claude Desktop と Aside で確認済み）。ログインシェルなら、Homebrew、nvm、システムへのインストールなど、どこにあっても npx を見つけられます。ターミナルベースのクライアント（Claude Code、Codex）では、通常の npx -y lupa-mcp で問題ありません。

エージェントへ：シェルから lupa-search を実行しないでください。 サンドボックス化されたエージェントのシェル（Aside、Codex）は、App Store 署名済みの CLI を起動時に終了させます — 終了コードは 133 または 134 です。代わりにこの MCP サーバーを登録してください。サンドボックスの外で起動します。 詳細なガイド：https://lupa.kr/agents.html

ツール

lupa_search

引数	デフォルト	意味
query	—	以下の構文を参照
limit	10	返す検索結果数（最大 50）
names_only	false	ファイル名のみを検索し、内容は無視します（高速）
snippet_chars	160	各スニペットの文字数を制限します（0 = 制限なし）

lupa_read

Lupa がファイルから抽出済みのテキストを返します。元ファイルを読み取るより低コストで、エージェントが解析できない形式にも対応します。Lupa 2.0 以降が必要です。

引数	デフォルト	意味
path	—	lupa_search が返す絶対パス
max_chars	8000	返すテキストの上限（0 = 制限なし）

クエリ構文

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

韓国語と中国語の接頭辞も使用できます（종류: 크기: 날짜: / 种类: 大小: 日期:）。

韓国語は適切に処理されます。複合語の一部や、語に付いた助詞でも一致します。Spotlight が苦手とする部分です。

監査ログ

ツールの呼び出しはすべて Mac に記録されるため、エージェントが何を検索し、どのファイルを表示されたかを確認できます。

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

各行には時刻、呼び出したクライアント（例：Claude Code、Cursor）、ツール、クエリまたはパス、返されたパス、成功したかどうかが記録されます。スニペットとドキュメントのテキストは記録されません。 ファイルを読めるのはあなただけ（0600）で、Mac の外に送信されることもありません。

各行はハッシュチェーンで連結されています。各エントリーには前のエントリーのハッシュが含まれるため、行の編集や削除が検出されます。これによりログは改ざんの検知が可能になりますが、改ざんを防止するものではありません — ファイル全体を削除して作り直すことは可能です。

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

LUPA_MCP_AUDIT=off で無効にするか、LUPA_MCP_AUDIT_PATH=/path/to/file.jsonl で保存先を変更できます。

プライバシー

すべての処理は Mac 上で行われます。Lupa にはネットワーク関連のコードが一切なく、このサーバーは Lupa に同梱されたコマンドラインツールを起動して、その結果をエージェントに渡すだけです。アップロードもテレメトリーもありません。

注意事項

• Lupa の無料インデックスは、最大 50,000 ファイルをカバーします。このサーバーはアプリがインデックス化した内容をそのまま引き継ぎます。ここには個別の制限や有料化はありません。
• 各ドキュメントの冒頭部分のみがインデックス化されるため、lupa_read は長いファイルを途中で切り詰めます。
• Lupa が通常とは異なる場所にインストールされている場合は、LUPA_SEARCH_PATH にアプリバンドル内の lupa-search バイナリを設定してください。

トラブルシューティング

メッセージ	対処方法
"Lupa를 찾을 수 없습니다" / 見つかりません	Mac App Store から Lupa をインストールしてください
"검색 인덱스가 없습니다"	Lupa を開き、フォルダーを追加して、インデックス化が完了するまで待ってください
"본문 읽기를 지원하지 않습니다"	Lupa を 2.0 以降にアップデートしてください
存在することが分かっているファイルが検索結果に表示されない	そのフォルダーが Lupa に登録されていない可能性があります

ライセンス

MIT