Lupa — local file search for your Mac

Name: Lupa — local file search for your Mac
Author: under71

von under71Version 0.3.1i★ –iLäuft auf deinem Computer

Name in der Registryio.github.under71/lupa-mcp

Installieren

Überblick

Beschreibung vom Entwickler (englisches Original)

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

Die drei Säulen von PopNx MCP

Diese drei werden nie zu einer Punktzahl zusammengefasst: Meinungen, Messungen und Beliebtheit sind verschiedene Dinge.

Stimmen der NutzeriNoch keine BewertungenBewertungen starten in einem späteren Schritt zusammen mit Benutzerkonten
Unsere Basischecksi1 von 1 bestandenAnhand öffentlicher Informationen geprüft; Code noch nicht gescannt
NutzungiNoch nicht gemessen★ –

Was du damit machen kannst

Für diesen Server haben wir noch keine Zusammenfassung in einfacher Sprache geschrieben. Unten stehen die Fakten, die wir aus der Registry gelesen haben.

Verbindung: Läuft auf deinem Computer
Transport: stdio
Kategorie: Suche & KI-Gedächtnis

Installation

Wähle die KI-App, die du nutzt, und kopiere die Einstellungen.

Bevor du installierst

Basischecks: 1 von 1 bestanden
Läuft auf deinem Computer mit den Rechten deines Benutzerkontos (Dateien, Netzwerk, Apps).
Die Registry nennt keinen Schlüssel zum Eintragen.

Du brauchst

npmNode.js installiert (für den Befehl npx)

Welche App nutzt du?

ClaudeClaude CodeCursorVS CodeChatGPT

Wähle oben deine App. Wir merken sie uns, damit der Button beim nächsten Mal „In … installieren“ anzeigt.

Öffne Claude Desktop → Settings → Developer → Edit Config und füge dies in claude_desktop_config.json ein

{
  "mcpServers": {
    "lupa": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}

Führe das in deinem Terminal aus

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

In Cursor öffnen

Oder kopier die Einstellungen selbst

In .cursor/mcp.json in deinem Projekt oder in ~/.cursor/mcp.json einfügen

{
  "mcpServers": {
    "lupa": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}

Dein Browser fragt, ob er die App öffnen darf, dann zeigt die App die Einstellungen und bittet dich um Bestätigung. Schlüsselwerte bleiben leer, damit du sie selbst einträgst.

In VS Code öffnen

Oder kopier die Einstellungen selbst

In .vscode/mcp.json in deinem Projekt einfügen

{
  "servers": {
    "lupa": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}

Dein Browser fragt, ob er die App öffnen darf, dann zeigt die App die Einstellungen und bittet dich um Bestätigung. Schlüsselwerte bleiben leer, damit du sie selbst einträgst.

Dieser Server läuft auf deinem Computer, und ChatGPT kann sich nur mit Servern im Internet verbinden. Wähle eine andere App.

Deine Auswahl bleibt in einem Cookie auf diesem Gerät; kein Konto nötig.

Diese Einstellungen werden aus dem Registry-Eintrag des Entwicklers erzeugt. Wenn in der README etwas anderes steht, folge der README.

Was er kann

Läuft auf deinem Computer; die Tool-Liste erscheint nach der Installation in deiner KI-App.

Basischecksi

Wir prüfen Informationen, die jeder sehen kann; den Code haben wir nicht gelesen. Checks, die nicht zutreffen, werden nicht mitgezählt. · Geprüft am 7. Nov. 2026

✓ Bestanden
Entwickler passt zum Repo
Der Registry-Name wurde mit dem GitHub-Konto under71 bestätigt, dem das Repo gehört
… Noch nicht geprüft
Wird noch gepflegt
Dieses Repo haben wir noch nicht von GitHub gelesen
… Noch nicht geprüft
Hat eine Lizenz
Dieses Repo haben wir noch nicht von GitHub gelesen
– Nicht zutreffend
Endpunkt antwortet
Dieser Server läuft auf deinem Computer; es gibt keinen Endpunkt im Internet
– Nicht zutreffend
Anmeldung mit OAuth
Läuft auf deinem Computer und nutzt stattdessen lokale Einstellungen
… Noch nicht geprüft
Keine versteckten Anweisungen in Tool-Beschreibungen
Läuft auf deinem Computer; Tool-Listen können wir nur von Endpunkten im Internet lesen

Im Vergleich mit anderen in Suche & KI-Gedächtnisi

Mehr Sterne als 0 % der anderen 7254 Server in dieser Kategorie
Neuer in der Registry veröffentlicht als 74 % der anderen 7254 Server in dieser Kategorie
Basischecks gleich gut wie oder besser als bei 100 % der anderen 7254 Server in dieser Kategorie

Verglichen mit allen aktiven Servern dieser Kategorie in der Registry. Sterne zählen nur, wenn dem Herausgeber das Repo gehört.

Häufige Fragen

Ist Lupa — local file search for your Mac sicher?

Er hat 1 von 1 zutreffenden Basischecks bestanden. Den Code haben wir nicht gelesen. Bevor du einen Schlüssel oder Token hinzufügst, sieh nach, welche Zugriffe der Server verlangt, und nutze einen Schlüssel, der nur die Berechtigungen hat, die du brauchst.

Welche Schlüssel oder Codes braucht er?

Die Registry nennt keinen erforderlichen Schlüssel, manche Server bitten dich aber bei der ersten Nutzung, dich anzumelden.

Läuft er auf meinem Computer oder in der Cloud?

Er läuft auf deinem Computer. Deine KI-App startet ihn bei Bedarf, und die Daten laufen nicht über die Server des Entwicklers (außer der Server ruft selbst einen Onlinedienst auf).

Wird er noch gepflegt?

Das GitHub-Repo wurde zuletzt – geändert, und die neueste Version (0.3.1) kam vor 13 Tagen in die Registry.

Welche Apps können ihn nutzen?

Apps, die MCP unterstützen, etwa Claude Desktop, Claude Code, Cursor und VS Code. Außerdem brauchst du Node.js auf deinem Computer.

Was kann ich stattdessen nutzen?

In derselben Kategorie: Context7, Codebase Memory, Exa

Alternativen

Server derselben Kategorie von anderen Entwicklern, sortiert nach Sternen.

So liest du eine Karte:★ GitHub-SterneiDrei Säulen: Bewertungen · Checks · NutzungiAktualisiert = neueste Version in der Registry veröffentlichti

Context7

von upstash

Up-to-date docs for AI agents

Computer oder Cloud★ 64.224MITAktualisiert heute

Installieren

Codebase Memory

von DeusData

Codebase knowledge graph for AI agents — 162 languages, sub-ms queries, 99% fewer tokens.

Läuft auf deinem Computer★ 48.148MITAktualisiert vor 20 Tagen

Installieren

Exa

von exa-labs

Connect AI agents to Exa for web search, content fetching, and multi-step research.

Läuft in der Cloud★ 5.213MITAktualisiert letzten Monat

Installieren

README vom Entwickler

README öffnen

Unverändert aus dem Repo des Entwicklers übernommen. PopNx MCP hat den Inhalt weder geprüft noch empfiehlt es ihn. HTML, Bilder und Skripte wurden entfernt. Links führen von dieser Website weg.

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.

"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

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

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

"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

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.

Audit log

Every tool call is recorded on your Mac so you can see what an agent searched for and which files it was shown:

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

Each line has the time, the calling client (e.g. Claude Code, Cursor), the tool, the query or path, the paths returned, and whether it succeeded. Snippets and document text are not logged. The file is readable only by you (0600) and never leaves the Mac.

Lines are hash-chained: each entry includes the hash of the previous one, so editing or removing a line is detected. This makes the log *tamper-evident*, not tamper-proof — deleting the whole file and starting over is still possible.

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

Turn it off with LUPA_MCP_AUDIT=off, or move it with LUPA_MCP_AUDIT_PATH=/path/to/file.jsonl.

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

Lupa — local file search for your Mac

Überblick

Die drei Säulen von PopNx MCP

Was du damit machen kannst

Installation

Bevor du installierst

Was er kann

Basischecksi

Entwickler passt zum Repo

Wird noch gepflegt

Hat eine Lizenz

Endpunkt antwortet

Anmeldung mit OAuth

Keine versteckten Anweisungen in Tool-Beschreibungen

Im Vergleich mit anderen in Suche & KI-Gedächtnisi

Häufige Fragen

Alternativen

Context7

Codebase Memory

Exa

README vom Entwickler

lupa-mcp

Why this instead of find/grep

Requirements

Install

Tools

lupa_search

lupa_read

Query syntax

Audit log

Privacy

Notes

Troubleshooting

License

`lupa_search`

`lupa_read`