obsidian-cli-mcp

obsidian-cli-mcp ist ein MCP-Server für die offizielle Obsidian-CLI. Er stellt Obsidian-Vault-Suche, Notiz-, Aufgaben-, Datei-, Link- und native Canvas-Operationen für einen MCP-Client bereit. Der Server ersetzt Obsidian nicht: Die CLI leitet Anfragen an die laufende Obsidian-Desktop-App weiter.

Der Standardtransport ist lokales stdio. Remote Streamable HTTP ist als erweiterte, separat abgesicherte Einrichtung verfügbar; für die lokale Nutzung ist es nicht erforderlich.

Anforderungen

• macOS mit installierter und laufender Obsidian Desktop-App.

• Die offizielle Obsidian-CLI in Obsidian aktiviert: Einstellungen → Allgemein → Befehlszeilenschnittstelle, dann obsidian in Ihrem PATH registrieren.

• Node.js 18 oder neuer, um das veröffentlichte Paket auszuführen. Bun wird nur benötigt, um diesen Quellcode-Checkout zu erstellen oder zu entwickeln.

Dieses Projekt erfordert die Desktop-CLI. Es unterstützt obsidian-headless nicht. Die Obsidian-App muss geöffnet bleiben, während der MCP-Server verwendet wird.

Überprüfen Sie zuerst die Obsidian-Seite:

command -v obsidian
obsidian version
obsidian vault

Schnellstart mit npm

Starten Sie das veröffentlichte Paket v0.4.1 aus einem beliebigen Verzeichnis:

npx --yes --package=@dariuscodes/obsidian-cli-mcp@0.4.1 obsidian-cli-mcp

Der Befehl spricht MCP über stdio und wartet auf einen MCP-Client. Er druckt absichtlich keine Protokolldaten auf das Terminal. Diagnosen gehen an stderr.

Für einen Quellcode-Checkout stattdessen:

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

Für die lokale Standardkonfiguration sind kein Vault-Name, Vault-Pfad, Token, Cloudflare-Konto, LaunchAgent oder Konfigurationsdatei erforderlich. Der Server verwendet den aktiven Vault, den Obsidian über die offizielle CLI bereitstellt.

Einen MCP-Client verbinden

Für einen Client, der eine mcpServers-Konfiguration akzeptiert, verwenden Sie den npm-Befehl:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/obsidian-cli-mcp@0.4.1",
        "obsidian-cli-mcp"
      ]
    }
  }
}

Wenn der Client Ihr Shell-PATH nicht erbt, ersetzen Sie npx durch den absoluten Pfad, der von command -v npx ausgegeben wird. Für einen Quellcode-Checkout verwenden Sie command: "node" und args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"].

Starten Sie den Client nach der Änderung seiner MCP-Konfiguration neu. Die erste nützliche Sequenz ist:

1. Rufen Sie vault_search mit einer Abfrage auf, die in Ihrem Vault vorhanden sein sollte, z. B. { "query": "meeting", "limit": 10 }.

2. Übergeben Sie einen zurückgegebenen Pfad an note_read, z. B. { "path": "<path returned by vault_search>" }.

3. Vorschau einer sicheren Notizänderung, bevor Sie sie anwenden:

   {
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }

   Dies ist ein note_create-Aufruf. Er gibt die geplante Aktion und den genauen CLI-Befehl zurück, ohne den Vault zu verändern. Verwenden Sie dryRun: false nur, nachdem Sie den Plan überprüft haben. dryRun ist eine Vorschau, keine Autorisierungsgrenze.

4. Für Canvas: Vorschau einer nativen Canvas-Datei und eines Textknotens:

   {
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }

   Dies ist ein canvas_create-Aufruf. Überprüfen Sie den Plan und rufen Sie ihn dann mit dryRun: false auf, wenn Sie die Datei erstellen möchten. Verwenden Sie canvas_read, um danach das native .canvas-JSON zu inspizieren. Canvas-Tools bewahren unbekannte Felder, validieren Knoten-/Kantenreferenzen und erfordern keine beliebige Auswertung.

Konfiguration und sichere Standardeinstellungen

Eine leere oder fehlende Konfiguration ist für einen Vanilla-Obsidian-Vault verwendbar. Die optionale .obsidianmcprc.yaml wird aus dem Arbeitsverzeichnis des Servers ermittelt. Für Clients mit unvorhersehbarem Arbeitsverzeichnis setzen Sie OBSIDIAN_MCP_CONFIG auf einen expliziten Konfigurationsdateipfad.

Die Standardrichtlinie ist bewusst lokal und begrenzt:

• Der v0.4.0-Server stellt kein generisches obsidian_eval-Tool bereit. eval.enabled ist standardmäßig false; interne feste Eval-Snippets, die von einigen sicheren Operationen verwendet werden, sind keine vom Benutzer bereitgestellte JavaScript-Ausweichmöglichkeit.

• Importe aus beliebigen lokalen Dateien sind deaktiviert, bis imports.allowedRoots explizit konfiguriert ist. URLs werden nie abgerufen.

• .obsidian, .git, .trash, .Trash, Trash und .DS_Store-Pfadsegmente sind standardmäßig blockiert. Fügen Sie paths.allow für einen engeren Vault-Bereich hinzu und fügen Sie projektspezifische paths.deny-Präfixe für sensiblere Inhalte hinzu.

• Mutationen legen dryRun offen. file_delete erfordert confirm: true und note_delete verwendet standardmäßig den Obsidian-Papierkorb; dauerhaftes Löschen erfordert die explizite Konfiguration delete.mode: hard.

• Git-Autocommit ist standardmäßig deaktiviert.

Schreibgeschützte Voreinstellung

Verwenden Sie eine explizite Zulassungsliste, wenn ein MCP-Client den Vault nur inspizieren soll:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - file_read_binary_metadata
    - canvas_read

Sichere lokale Voreinstellung

Die Standardeinstellung hat sichere lokale Schutzmaßnahmen, ist aber nicht schreibgeschützt. Für eine explizite sichere lokale Oberfläche, die normale Notizbearbeitung und Canvas-Erstellung erlaubt, aber Löschung, Dateiimporte, Dateilebenszyklusoperationen und beliebige Auswertung weglässt:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - canvas_read
    - canvas_create
    - canvas_upsert_nodes
    - canvas_upsert_edges
    - canvas_add_node
    - canvas_add_edge
    - canvas_auto_layout
    - canvas_open
    - note_create
    - note_append
    - note_set_frontmatter
    - note_replace_range
    - note_insert_at
    - note_replace
    - note_insert
    - daily_open
    - daily_append
    - task_create
    - task_update
delete:
  mode: trash
eval:
  enabled: false
imports:
  allowedRoots: []

Vollständige vertrauenswürdige lokale Voreinstellung

Lassen Sie tools.allow weg, um die vollständige integrierte Tool-Oberfläche bereitzustellen, während die standardmäßig geschützten Pfade, Papierkorblöschung, deaktivierte Importe und deaktiviertes obsidian_eval beibehalten werden. Wenn Importe benötigt werden, konfigurieren Sie nur ein dediziertes lokales Quellverzeichnis:

imports:
  allowedRoots:
    - /absolute/path/to/approved-imports
  maxBytes: 26214400
  collision: increment
delete:
  mode: trash
eval:
  enabled: false

Siehe docs/configuration.md für alle Felder und examples/ für Notizorganisations-Voreinstellungen.

Lokales stdio versus Remote-HTTP

Lokales stdio startet einen Serverprozess direkt vom MCP-Client. Es ist die empfohlene Installation: Es gibt keinen lauschenden Socket, keine Remote-Authentifizierung, kein Cloudflare-Setup und keinen öffentlichen Endpunkt.

Streamable HTTP ist ein optionaler erweiterter Modus für einen Client, der kein lokales stdio verwenden kann. Es bindet nur an Loopback und weigert sich zu starten, ohne entweder Cloudflare Access JWT-Validierung oder ein starkes Capability-Token. Platzieren Sie es hinter einem TLS-, authentifizierten Reverse-Proxy oder Tunnel; binden Sie es nicht an 0.0.0.0. Siehe docs/remote-cloudflare.md für das generische erweiterte Setup und seine Sicherheitsabwägungen.

Tool-Oberfläche

Der Standardserver bewirbt 42 reguläre Tools:

• Lesen: vault_search, note_read, note_list, vault_tags, unresolved_links, tasks_list, note_diff, backlinks_get, outlinks_get, file_read_binary_metadata, canvas_read.

• Schreiben und Workflow: note_create, note_append, note_set_frontmatter, daily_open, daily_append, note_replace_range, note_insert_at, note_replace, note_insert, task_create, task_update, note_transition.

• Dateien und Anhänge: file_import, attachment_import, note_attach, attachment_embed, file_move, file_rename, file_delete, note_rename, note_move, folder_create, note_delete.

• Canvas: canvas_create, canvas_upsert_nodes, canvas_upsert_edges, canvas_remove, canvas_open, canvas_add_node, canvas_add_edge, canvas_auto_layout.

Alle mutierenden Tools akzeptieren dryRun. Tool-Anmerkungen identifizieren schreibgeschützte und destruktive Operationen für kompatible MCP-Clients.

Einschränkungen und Sicherheit

Obsidian Desktop muss ausgeführt werden, seine offizielle CLI muss aktiviert sein und der aktive Vault muss für diese Desktop-Sitzung verfügbar sein. Dieser Server ist keine Sandbox und unterstützt obsidian-headless nicht.

Vault-Inhalte sind nicht vertrauenswürdige Daten. Notizen, Canvas-Text, Aufgabentext und Suchergebnisse können Prompt-Injection-Anweisungen enthalten; ein MCP-Client sollte sie als Daten behandeln und niemals Anweisungen befolgen, die in einem Vault gefunden werden, nur weil sie von einem Tool zurückgegeben wurden. Tool-Ausgaben können auch sensible Vault-Inhalte enthalten, verbinden Sie sich daher nur mit Clients, denen Sie vertrauen.

Lesen Sie SECURITY.md, bevor Sie Remote-HTTP, Importe, hartes Löschen oder eine breite Mutations-Zulassungsliste aktivieren. Melden Sie Sicherheitsprobleme privat, wie dort beschrieben.

Entwicklung und CI

Der Quellcode-Checkout verwendet Bun, während die veröffentlichte Binärdatei auf Node läuft:

bun install
bun run typecheck
bun test
bun run build:schema
bun run build
bun run smoke:stdio
git diff --check
npm pack --dry-run --json

Der Offline-Studio-Smoke-Test überprüft den Einstiegspunkt des gebauten Pakets, MCP-Initialize, tools/list, die erwartete Tool-Oberfläche und das Fehlen von obsidian_eval. Der echte Obsidian-Smoke-Test ist separat und erfordert eine Benutzersitzung mit laufendem Obsidian:

OBSIDIAN_CLI_BINARY=obsidian \
  OBSIDIAN_MCP_CONFIG=/absolute/path/to/your/config.yaml \
  OBSIDIAN_MCP_VAULT="your-vault-name" \
  bun run smoke:live

GitHub Actions führt nur Offline-Gates aus; es hängt nicht von Obsidian Desktop oder einem echten Vault auf einem gehosteten Runner ab.

Lizenz

MIT