lupa-mcp

당신의 AI 에이전트가 Mac의 문서를 그 안에 적힌 내용을 기준으로 검색하게 하세요.

Lupa용 MCP 서버입니다. 자체 인덱스를 가진 macOS 파일 검색 앱이죠. 에이전트가 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, 일반 텍스트, 한글 HWP/HWPX, 그리고 OCR로 판독한 스캔 PDF까지 지원합니다.

find/grep보다 이 방식이 나은 이유

마지막 행이 핵심입니다. 디스크 접근 권한을 부여하지 않아도 에이전트가 문서 내용을 얻을 수 있습니다.

Related MCP server: LocalSynapse

요구사항

Lupa 앱이 반드시 설치되어 있어야 합니다 — 이 서버는 Lupa가 만든 인덱스를 읽을 뿐이며, 스스로 인덱싱하지 않습니다.

1. Mac App Store에서 무료 Lupa를 설치하세요: https://lupa.kr

2. Lupa를 열고 검색하려는 폴더를 추가한 다음 인덱싱이 끝날 때까지 기다리세요.

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_read는 파일에서 Lupa가 이미 추출한 텍스트를 반환합니다. 원본 파일을 직접 읽는 것보다 가볍고, 에이전트가 파싱할 수 없는 형식에서도 동작합니다. Lupa 이상 버전이 필요합니다.

쿼리 문법

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를 설정하세요.

문제 해결

라이선스

MIT