lupa-mcp

AIエージェントに、Mac上のドキュメントを ―― そこに書かれている内容で ― 検索させましょう。

Lupa用のMCPサーバーです。Lupaは、独自のインデックスを備えるmacOS向けファイル検索アプリです。エージェントがLupaに問い合わると、Lupaはローカル・インデックスから約30msで回答します。ネットワクに触れるものは一切ありません。

"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、プレーンテキスト、 ハングル HWP/HWPX、そして OCRで読み取ったスキャンPDF。

なぜfind/grepの代わりに、これなのか

最後の行がこのテーブルのポイントです。エージェントはドキュメントの本文を取得できますが、あなたがエージェントにディスクへのアクセスを許可する必要はありません。

Related MCP server: LocalSynapse

必要條

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": "npx", "args": ["-y", "lupa-mcp"] }
  }
}

以上です。APIキーも、アカウントも、設定も必要ありません。

ツール

lupa_search

lupa_read

Lupaがすでにファイルから抽出したテキストを返します。原本を読むより軽量で、エージェントがパースできない形式でも動きます。Lupa 1.1以降が必要です。

• 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上で動作します。Lupaにはネットワ・コードが一切ありません。本サーバーは、Lupaに同梱されたコマンドライン・ツールを動して、結果をエージェントへ返すだけです。何かがアップロードされることはなく、テレメトリーもありません。

注記

• Lupaの無料インデックスは最大50,000ファイルまでが対です。本サーバーはアプリがイノックスしたものをそのまま継承するだけであり、別途の制限や有料ウォールはありません。

• 各ドキュメントの冒頭のみがイノックスされるため、長いファイルでは、lupa_read で内容が途中で切られます。

• Lupaが上の場所にインストールされている場合は、アプリ・バンドル内の lupa-search バイナリを指すように環境変数 LUPA_SEARCH_PATH を設定してください。

トラブルシューティング

• メ ッセージ: "Lupaを見つけられません"

  対処: Mac App StoreからLupaをインストールす。

• メッセージ: "검색 인덱스가 없습니다"

  対処: Lupaを起動しフォルダを追加して、インジックス完了を待つ。

• メッセージ: "본문 읽기를 지원하지 않습니다"

  対処: Lupaを1.1以降にアップデートす。

• 存在するはずのファイルに6:0件

  対処: そのフォルダがLupaに登録されていない恐怕があります。

ライセンス

MIT