obsidian-cli-mcp ist ein MCP-Server für die offizielle Obsidian-CLI. Er stellt Obsidian-Vault-Suche, Notizen, Aufgaben, Dateien, Links 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; es ist für die lokale Nutzung nicht erforderlich.
macOS mit installierter und laufender Obsidian Desktop-App.
Die offizielle Obsidian-CLI in Obsidian aktiviert: Einstellungen → Allgemein → Befehlszeilenschnittstelle, dann obsidian auf 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 vaultRelated MCP server: Obsidian MCP Server
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-mcpDer Befehl spricht MCP über stdio und wartet auf einen MCP-Client. Er gibt absichtlich keine Protokolldaten auf dem Terminal aus. 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.jsFür den lokalen Standard 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.
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 Ihre 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 einer Änderung seiner MCP-Konfiguration neu. Die erste nützliche Sequenz ist:
Rufen Sie vault_search mit einer Abfrage auf, die in Ihrem Vault vorhanden sein sollte, z. B. { "query": "meeting", "limit": 10 }.
Übergeben Sie einen zurückgegebenen Pfad an note_read, z. B. { "path": "<path returned by vault_search>" }.
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 ändern. Verwenden Sie dryRun: false erst nach Prüfung des Plans. dryRun ist eine Vorschau, keine Autorisierungsgrenze.
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 anschließend canvas_read, um das native .canvas-JSON zu inspizieren. Canvas-Tools bewahren unbekannte Felder, validieren Knoten-/Kantenreferenzen und erfordern keine beliebige Auswertung.
Eine leere oder fehlende Konfiguration ist für einen einfachen Obsidian-Vault verwendbar. Die optionale .obsidianmcprc.yaml wird aus dem Server-Arbeitsverzeichnis 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 Auswertungs-Snippets, die von einigen sicheren Operationen verwendet werden, sind keine benutzerbereitgestellte 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.
Verwenden Sie eine explizite Zulassungsliste, wenn ein MCP-Client nur den Vault 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_readDie 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: []Lassen Sie tools.allow weg, um die vollständige integrierte Tool-Oberfläche verfügbar zu machen, 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: falseSiehe docs/configuration.md für alle Felder und examples/ für Notizorganisations-Voreinstellungen.
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 Fähigkeitstoken. 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.
Der Standardserver bewirbt 43 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.
Batch: vault_batch führt aktivierte Lesevorgänge aus und zeigt aktivierte Mutationen mit args.dryRun: true, Abhängigkeits-Gating, stabile Ergebnisse in Eingabereihenfolge und eine begrenzte batch.maxParallelism (Standard 4, Maximum 8).
Alle mutierenden Tools akzeptieren dryRun. Tool-Anmerkungen identifizieren schreibgeschützte und destruktive Operationen für kompatible MCP-Clients.
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 daher nur 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.
Der Quellcode-Checkout verwendet Bun, während das veröffentlichte Bin 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 --jsonDer Offline-stdio-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:liveGitHub Actions führt nur Offline-Gates aus; es hängt nicht von Obsidian Desktop oder einem echten Vault auf einem gehosteten Runner ab.
This server cannot be deployed
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
