mcp-for-spotlight

Ein kleiner MCP-Server (Model Context Protocol), der die macOS-Spotlight-Suche als Tools bereitstellt. Er kapselt mdfind (Volltext- und Metadaten-Suche über den Spotlight-Index) und mdls (Metadaten einer Datei). Systemweite Dateisuche, nicht auf eine App beschränkt.

Was ist ein MCP-Server?

MCP (Model Context Protocol) ist ein offener Standard, über den KI-Anwendungen (der Host, etwa Claude Desktop oder Claude Code) mit externen Werkzeugen und Daten sprechen. Ein Server stellt Fähigkeiten (Tools) bereit und weiß selbst nichts von KI. Kommunikation über JSON-RPC 2.0, hier per stdio.

Warum Spotlight statt locate oder AppleScript

• Spotlight (mdfind) indexiert Datei-Inhalt und Metadaten (Betreff, Autor, Typ, Datum) und wird live aktualisiert. Der richtige Index für Inhaltssuche.
• locate kennt nur Datei-Pfade/-Namen, keinen Inhalt, und ist oft veraltet oder inaktiv.
• AppleScript-whose (etwa in Mail) ist ein linearer Scan ohne Index.

Tools

Tool	Zweck
spotlight_search	Dateien per mdfind finden: Freitext, Dateiname oder rohe Spotlight-Abfrage
spotlight_metadata	Spotlight-Metadaten einer Datei per mdls lesen

spotlight_search erwartet genau eine Suchart:

• text — Freitext (Volltext + Metadaten), z. B. "Quartalsbericht"
• name — Teilstring im Dateinamen
• query — rohe Spotlight-Abfrage, z. B. kMDItemContentType == "com.adobe.pdf" && kMDItemFSName == "*Rechnung*"c

Optional onlyIn (auf ein Verzeichnis begrenzen) und limit (Vorgabe 50).

Installation

npm install

Kein Build-Schritt: reines ESM-JavaScript, läuft direkt mit Node (>= 18).

Full Disk Access

Geschützte Orte (z. B. ~/Library/Mail, ~/Library/Messages) liefern nur Treffer, wenn der ausführende Prozess Full Disk Access hat (Systemeinstellungen → Datenschutz & Sicherheit → Festplattenvollzugriff, dort das Terminal bzw. den Node-Host freigeben). Ohne FDA sind normale Nutzerdateien trotzdem durchsuchbar.

Lokal testen

npm run inspect

Registrieren

Claude Code:

claude mcp add spotlight -- node /absolute/path/to/mcp-for-spotlight/src/index.js

Claude Desktop, in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "spotlight": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-for-spotlight/src/index.js"]
    }
  }
}

Beispiele

spotlight_search  name="Rechnung" onlyIn="/Users/me/Documents"
spotlight_search  query='kMDItemContentType == "com.adobe.pdf"' onlyIn="/Users/me/Downloads"
spotlight_metadata path="/Users/me/Downloads/x.pdf" attributes=["kMDItemContentCreationDate"]

Lizenz

MIT