obsidian-cli-mcp

Ein MCP-Server, der Claude und anderen MCP-Clients die volle Kontrolle über einen laufenden Obsidian-Tresor über die offizielle Obsidian-CLI (Obsidian 1.12+) gibt, mit schnellen direkten Dateisystem-Lesevorgängen, wo die Korrektheit dies erlaubt.

Begleitprojekt zu things-for-mac-mcp.

Was macht dieses Projekt anders?

Die meisten Obsidian-MCP-Server kommunizieren entweder mit einem Community-REST-Plugin oder lesen direkt den Tresor-Ordner. Ersteres erfordert die Installation und das Vertrauen in ein Plugin. Letzteres bricht stillschweigend Wikilinks, sobald es eine Datei verschiebt oder umbenennt, weil nur Obsidian jeden Link, Alias und Embed kennt, der darauf verweist.

Dieser Server leitet jede Operation nach Fähigkeit weiter:

Die Architektur spiegelt exakt das Schwesterprojekt wider:

Die Regel hinter der Aufteilung: Massenlesevorgänge gehen an das Dateisystem, weil sie Durchsatz benötigen, und alles, was verschiebt, umbenennt, löscht oder von Linkauflösung oder App-Zustand abhängt, geht durch die CLI, weil es Obsidians Wissen benötigt. Der Dateisystem-Adapter kann strukturell den Tresor nicht verändern, er exportiert überhaupt keine Schreibfunktion.

Voraussetzungen

• macOS-, Windows- oder Linux-Desktop mit Obsidian 1.12 oder neuer

• Die Obsidian-CLI aktiviert: Obsidian, Einstellungen, Allgemein, Befehlszeilenschnittstelle

• Obsidian muss laufen. Die CLI ist ein Client für die App, kein eigenständiges Binärprogramm. Dies ist nur für den Desktop, mobil wird nicht unterstützt.

• Node.js 18 oder neuer

Installation

git clone https://github.com/jabaho9523/obsidian-cli-mcp.git
cd obsidian-cli-mcp
npm install
npm run build

Mit einem MCP-Client verbinden

Claude (Desktop / Code)

Fügen Sie zu claude_desktop_config.json (Claude Desktop) hinzu oder führen Sie claude mcp add (Claude Code) aus:

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/obsidian-cli-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "YourVaultName"
      }
    }
  }
}

Verwenden Sie den absoluten Pfad zu node, nicht das bloße Wort. Über die GUI gestartete Apps erben nicht das PATH Ihrer Shell, daher schlägt "command": "node" bei vielen Clients stillschweigend fehl. Finden Sie Ihren mit which node.

Setzen Sie OBSIDIAN_VAULT, wenn Sie mehr als einen Tresor haben. Andernfalls zielt die CLI auf den zuletzt fokussierten Tresor ab, was eine schreckliche Eigenschaft für automatisierte Schreibvorgänge ist. Bei einem einzelnen Tresor fixiert der Server ihn automatisch beim Start.

Konfiguration

Schutzmaßnahmen

Drei Stufen, die durchgesetzt werden, bevor die Binärdatei überhaupt gestartet wird:

• Stufe 1, kostenlos: Lesevorgänge, Suchen und additive Schreibvorgänge (create_note, append_note, append_daily, set_property, update_task, capture).

• Stufe 2, erfordert confirm: true im Werkzeugaufruf: delete_note, move_note, rename_note, remove_property, run_obsidian_command, und über den Passthrough: history:restore, publish:*, plugin:enable/disable/reload, theme:*, snippet:*, sync, sync:restore, reload, template:insert, workspace:save/delete. Jeder Aufruf mit einem overwrite- oder permanent-Flag wird ebenfalls auf Stufe 2 hochgestuft.

• Stufe 3, blockiert, es sei denn, der Server läuft mit OBSIDIAN_MCP_ALLOW_DANGEROUS=1: eval, restart, plugin:install, plugin:uninstall, plugins:restrict, devtools, dev:cdp, dev:debug, dev:mobile, und delete_note mit permanent: true.

Eine ehrliche Anmerkung, was diese sind. Stufe 2 ist eine Geschwindigkeitsschwelle gegen versehentliche Aufrufe, keine Sicherheit: das aufrufende Modell kann selbst confirm: true setzen. Stufe 3 ist eine echte Grenze, weil nur derjenige, der die Serverumgebung konfiguriert, sie freischalten kann. Wenn Sie einen autonomen Agenten auf einen Tresor richten, der Ihnen wichtig ist, führen Sie ihn mit OBSIDIAN_MCP_READONLY=1, das jeden mutierenden Befehl vor dem Versand ablehnt, unabhängig von der Stufe.

Linksichere Verschiebungen und Umbenennungen

Die wichtigste Regel in diesem Projekt: Dateien werden niemals über das Dateisystem verschoben, umbenannt oder gelöscht. Obsidian aktualisiert jeden Wikilink im Tresor, wenn es die Operation durchführt. Ein einfaches mv tut das nicht.

Vorher, mit Projects/Roadmap.md, verlinkt von drei Notizen:

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

Nach move_note mit to: "Archive/2026 Roadmap.md":

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

Alle drei Links aktualisiert, einschließlich des Überschriftenankers und des Alias, weil Obsidian die Verschiebung durchgeführt hat. Eine Dateisystemverschiebung hätte drei defekte Links und keinen Fehler hinterlassen.

Warum hybrid? Die Leistungsbegründung

Jeder CLI-Aufruf ist eine vollständige IPC-Roundtrip durch die laufende Obsidian-App. Das ist korrekt, aber langsam: Das Lesen von 2.000 Notizen über obsidian read sind 2.000 Roundtrips, Minuten Echtzeit. Das Lesen von der Festplatte ist ein einziger Verzeichnisdurchlauf, weit unter einer Sekunde auf jeder SSD.

Daher gehen Massenlesevorgänge (Suche, Auflistungen, Tag- und Eigenschaftsscans, Exporte, Zusammenfassungen) an das Dateisystem, und die CLI ist reserviert für das, was nur Obsidian beantworten kann (Links, Aliase, Bases, Templates, App-Zustand) und für jeden Schreibvorgang. Um dies in Ihrem eigenen Tresor zu vergleichen, messen Sie die Zeit von search_notes gegen den Passthrough obsidian_cli mit ["search", "query=..."].

Fehlerbehebung

"Obsidian läuft nicht." Der häufigste Fehler. Die CLI benötigt die App geöffnet und vollständig geladen. Starten Sie Obsidian und versuchen Sie es erneut.

"Konnte die Obsidian-CLI-Binärdatei nicht finden." Aktivieren Sie die CLI in Obsidian unter Einstellungen, Allgemein, Befehlszeilenschnittstelle, oder setzen Sie OBSIDIAN_BIN auf die Binärdatei.

Timeouts beim ersten Befehl. Ein kalter Obsidian-Start kann die Standardeinstellung von 20s überschreiten. Erhöhen Sie OBSIDIAN_MCP_TIMEOUT.

Notizen werden als fehlend gelesen oder der Server fällt oft auf die CLI zurück. Wenn Ihr Tresor in iCloud mit aktiviertem "Mac-Speicher optimieren" liegt, existieren ausgelagerte Dateien nur als .name.icloud-Stubs. Der Server erkennt diese und liest sie über Obsidian, das sie erneut herunterlädt, anstatt leere Notizen zu melden. Massenscans überspringen ausgelagerte Dateien und geben dies in ihrer Ausgabe an.

Schreibvorgänge landen im falschen Tresor. Sie haben mehrere Tresore und kein OBSIDIAN_VAULT gesetzt. Der Server warnt darüber auf stderr beim Start. Legen Sie einen fest.

Werkzeuge erscheinen nicht im Client. Überprüfen Sie die MCP-Protokolle des Clients und prüfen Sie das Problem mit dem absoluten Node-Pfad oben.

Auf dem neuesten Stand bleiben

git pull && npm install && npm run build

Der Server sucht beim Start nach Updates, höchstens einmal alle 24 Stunden, und speichert das Ergebnis in ~/.config/obsidian-cli-mcp/update-check.json. Er schlägt offline stillschweigend fehl und gibt eine einzelne stderr-Zeile aus, wenn eine neuere Version existiert.

Werkzeuge (insgesamt 39)

Lesewerkzeuge (18)

Schreibwerkzeuge (16)

Alle Schreibvorgänge gehen durch die CLI. Jeder erfordert ein explizites file- oder path-Ziel, keiner kann auf die aktuell aktive Datei zurückfallen.

run_obsidian_command ist die weiteste Tür im Server: Sie erreicht jede Aktion der Befehlspalette, einschließlich derer von Community-Plugins. Sie ist bewusst freigegeben und auf Stufe 2 abgesichert.

Workflow-Tools (4)

Notausstieg (1)

MCP-Ressourcen

Die Client-Unterstützung für Ressourcen variiert, Claude Desktop zeigt sie derzeit nicht an.

MCP-Prompts

Architektur

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

Tests laufen gegen eine Stub-Binärdatei, die ihr volles argv scannt und angewiesen werden kann, fehlzuschlagen, hängen zu bleiben oder übermäßig große Ausgaben zu erzeugen, sodass die gesamte Testsuite ohne installiertes Obsidian besteht:

npm test

Support

Probleme und Funktionsanfragen: GitHub Issues.

Mehr vom Autor

• things-for-mac-mcp, der zugehörige MCP-Server für Things 3

Lizenz

MIT