使用说明

Obsidian CLI MCP Server

Datenschutz-Warnung: Alle Notizen, die ueber diesen MCP-Server abgefragt werden, landen im Kontext des verwendeten LLM. Bei Cloud-LLMs (ChatGPT, Claude, Gemini etc.) bedeutet das: Deine Notizen koennten fuer das Training verwendet werden und waeren nach der Trainingsphase potenziell fuer alle Nutzer abrufbar. Verwende ein lokales LLM (z.B. Ollama, LM Studio), wenn deine Notizen vertrauliche oder persoenliche Inhalte enthalten — es sei denn, es ist dir egal, dass die ganze Welt deine Notizen kennt.

Ein MCP-Server der alle Vault-Operationen an die offizielle Obsidian CLI (v1.12+) delegiert und 32 Tools, MCP Resources sowie 4 MCP Prompts bereitstellt. Kein eigener Index, keine Datenbank — der Server kommuniziert direkt mit einer laufenden Obsidian-Instanz.

Alle Tool-Ausgaben mit Notiz-Pfaden enthalten sowohl einen klickbaren obsidian://-Link als auch den rohen Vault-Pfad in Backticks — AI-Agenten koennen letzteren direkt in read_note weiterverwenden ohne URL-Dekodierung. Alle Tool-Aufrufe werden in mcp-requests.log protokolliert.

Voraussetzungen

Voraussetzung	Details
Obsidian Desktop	Version 1.12+ muss installiert UND gestartet sein
Obsidian CLI aktiviert	In Obsidian: Settings > General > Command line interface aktivieren und registrieren
Node.js	Version 20+
macOS	CLI-Binary liegt standardmässig unter `/Applications/Obsidian.app/Contents/MacOS/Obsidian`

Wichtig: Die CLI verbindet sich zur laufenden Obsidian-App. Ohne gestartetes Obsidian geben alle Tools Fehler zurueck. Der Server startet trotzdem und loggt eine Warnung.

Installation

git clone https://github.com/FinPark/Obsidien-CLI-MCP-Server.git
cd Obsidien-CLI-MCP-Server
npm install
npm run build

Konfiguration

Alle Einstellungen sind optional und ueber Umgebungsvariablen steuerbar (oder via .env-Datei):

Variable	Default	Beschreibung
`VAULT_NAME`	`vault_arbeit`	Name des Obsidian-Vaults (Standard-Vault geaendert auf `vault_arbeit`)
`OBSIDIAN_BIN`	`/Applications/Obsidian.app/Contents/MacOS/Obsidian`	Pfad zum CLI-Binary
`PORT`	`8201`	HTTP-Port fuer den MCP-Server

Server starten

npm start

Ausgabe bei erfolgreichem Start:

[obsidian-mcp] Connected to Obsidian 1.12.7
[obsidian-mcp] StreamableHTTP server running on http://localhost:8201/mcp

MCP Tools (32)

Suche & Lesen

Tool	Beschreibung
`search_notes`	Volltextsuche (gleiche Syntax wie Obsidians Suchleiste); kurze Queries (1-2 Keywords) liefern beste Ergebnisse; jedes Ergebnis enthaelt `obsidian://`-Link + rohen Pfad in Backticks
`read_note`	Notizen lesen (bulk, per paths-Array)
`vault_stats`	Vault-Uebersicht: Name, Dateien, Ordner, Groesse, Top-Tags

Notiz-Management

Tool	Beschreibung
`create_note`	Notiz erstellen (mit interaktivem Formular fuer Metadaten)
`append_note`	Inhalt an Notiz anhaengen
`prepend_note`	Inhalt nach Frontmatter einfuegen
`rename_note`	Notiz umbenennen (Links werden automatisch aktualisiert)
`move_note`	Notiz verschieben (Smart-Matching, Link-Updates)
`delete_note`	Notiz loeschen (Papierkorb oder permanent)
`file_info`	Datei-Info fuer eine einzelne Datei (Groesse, Erstellt, Geaendert) — nicht fuer Schleifen
`list_files`	Dateien auflisten (Folder/Extension-Filter)
`list_recents`	Zuletzt geoeffnete Dateien (mit `obsidian://`-Links, ohne Datum)
`list_modified_notes`	Notizen nach Aenderungsdatum filtern — effizienter Einzelaufruf statt N x `file_info`

Ordner

Tool	Beschreibung
`list_folders`	Ordner auflisten (mit optionalem Filter)

Teilnehmer & Tags

Tool	Beschreibung
`list_participants`	Alle Teilnehmer mit Haeufigkeit
`list_tags`	Alle Tags mit Haeufigkeit
`update_tags`	Tags auf Notizen aendern (add/remove)
`rename_tag`	Tag vault-weit umbenennen
`delete_tag`	Tag vault-weit loeschen

Tasks

Tool	Beschreibung
`list_tasks`	Tasks auflisten (todo/done/daily, per Datei)
`toggle_task`	Task-Status aendern (toggle/done/todo)

Link-Analyse

Tool	Beschreibung
`list_backlinks`	Backlinks zu einer Notiz
`list_links`	Ausgehende Links einer Notiz
`list_orphans`	Verwaiste Notizen (keine eingehenden Links)
`list_deadends`	Sackgassen (keine ausgehenden Links)
`list_unresolved`	Broken Links im Vault

Properties (Frontmatter)

Tool	Beschreibung
`list_properties`	Alle Properties mit Typ und Haeufigkeit
`get_property`	Property-Wert einer Notiz lesen
`set_property`	Property setzen (text, list, number, checkbox, date, datetime)
`remove_property`	Property entfernen

Outline

Tool	Beschreibung
`get_outline`	Heading-Struktur einer Notiz (tree, json, md)

Recherche

Tool	Beschreibung
`research_chain`	Verfolgt die Vorgaenger-Kette (Frontmatter "Vorausgegangen") rueckwaerts bis zur Wurzel-Notiz. Liefert die komplette Kette chronologisch, plus alle Links und Backlinks der Ketten-Notizen. Sendet Progress Notifications (3 Schritte) waehrend der Ausfuehrung.

MCP Resources

Alle Markdown-Notizen des Vaults sind als MCP Resources unter dem Schema obsidian://note/{vault-relativer-pfad} erreichbar. Kompatible MCP-Clients koennen damit direkt auf einzelne Notizen zugreifen ohne explizite Tool-Aufrufe.

URI-Schema	Beschreibung
`obsidian://note/{path}`	Liest den Inhalt der Notiz am angegebenen Vault-Pfad

MCP Prompts (4)

Vordefinierte Prompts fuer haeufige Aufgaben — werden von kompatiblen MCP-Clients direkt als Slash-Commands oder Prompt-Picker angeboten:

Prompt	Beschreibung	Parameter
`meeting-summary`	Schreibt eine praegnante Zusammenfassung einer Meeting-Note	`note_path` (required)
`research-topic`	Strukturierter Ueberblick ueber die Themenhistorie via `research_chain`	`note_file` (required), `depth` (optional: full/short)
`daily-review`	Zeigt die heutige Daily Note und alle offenen Tasks	—
`link-suggestions`	Analysiert Links und schlaegt thematisch passende, noch nicht verlinkte Notes vor	`note_path` (required)

Request-Logging

Alle Tool-Aufrufe werden in mcp-requests.log im Projektverzeichnis protokolliert (zusaetzlich zu stderr). Format:

2026-03-30T10:15:00.000Z [CALL] tool=search_notes args={"query":"Solarertrag"}
2026-03-30T10:15:00.123Z [OK]   tool=search_notes → 342 chars
2026-03-30T10:15:01.000Z [ERROR] tool=read_note → File "foo.md" not found

Die Logdatei wird nicht rotiert — bei Bedarf manuell loeschen oder tail -f mcp-requests.log zum Live-Monitoring verwenden.

Architektur

HTTP Request (Port 8201)
    |
    v
StreamableHTTP Transport (Session-Management)
    |
    v
MCP Server (32 Tools registriert)
    |
    v
CLI Executor (src/cli/obsidian-cli.ts)
    |
    v
/Applications/Obsidian.app/Contents/MacOS/Obsidian
    |
    v
Laufende Obsidian-Instanz

Der CLI-Executor:

Fuehrt Befehle per execFile aus (kein Shell, sicher gegen Injection)
Filtert Startup-Noise aus stdout (Loading-Messages, Installer-Warnungen)
Stripped => Prefix bei eval-Befehlen
30 Sekunden Timeout pro Befehl
10 MB Buffer fuer grosse Ausgaben

Projektstruktur

src/
  index.ts              HTTP-Server, Session-Management
  server.ts             MCP-Server, Tool-Routing (v2.0.0, 31 Tools + Resources + Prompts)
  config.ts             VAULT_NAME, OBSIDIAN_BIN
  cli/
    obsidian-cli.ts     CLI-Wrapper: exec(), execJson(), Noise-Filtering
  resources/
    notes.ts            MCP Resources Handler — alle Markdown-Notes als obsidian://note/{path} URIs
  prompts/
    index.ts            4 MCP Prompts (meeting-summary, research-topic, daily-review, link-suggestions)
  tools/
    search-notes.ts     search_notes
    read-note.ts        read_note
    list-participants.ts
    list-tags.ts
    vault-stats.ts
    create-note.ts      mit Elicitation-Formular
    move-note.ts        mit Smart-Matching und Elicitation
    list-folders.ts
    manage-tags.ts      update_tags, rename_tag, delete_tag
    tasks.ts            list_tasks, toggle_task
    links.ts            list_backlinks, list_links, list_orphans, list_deadends, list_unresolved
    properties.ts       list_properties, get_property, set_property, remove_property
    outline.ts          get_outline
    note-management.ts  append_note, prepend_note, rename_note, delete_note, file_info, list_files, list_recents, list_modified_notes
    research-chain.ts   research_chain (Vorgaenger-Kette mit Links/Backlinks + Progress Notifications)
    elicitation.ts      tryElicit() Helper

Auto-Start mit launchd (macOS)

~/Library/LaunchAgents/com.obsidian-mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.obsidian-mcp</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/path/to/Obsidien-CLI-MCP-Server/dist/index.js</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardErrorPath</key>
  <string>/tmp/obsidian-mcp.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.obsidian-mcp.plist

Dependencies

Package	Zweck
`@modelcontextprotocol/sdk`	MCP-Server, Transport, Elicitation

Keine weiteren Runtime-Dependencies. Alles laeuft ueber die Obsidian CLI.

Troubleshooting

Problem	Loesung
`Obsidian CLI timed out`	Obsidian Desktop starten
`File "X" not found`	Dateiname pruefen — `file=` loest wie Wikilinks auf, `path=` erwartet den exakten Vault-Pfad
`EADDRINUSE: port 8201`	`lsof -ti:8201 \| xargs kill -9`
CLI gibt Warnings aus	Normal bei aelterem Installer — werden automatisch gefiltert
`search` gibt leere Ergebnisse	Kurze, einfache Queries verwenden (1-2 Keywords). Lange Compound-Queries liefern haeufig 0 Ergebnisse. Obsidian-Syntax: `tag:#AI` statt `#AI`
Read-Note schlaegt fehl	Bei `file=`-Aufloesung: `.md`-Suffix nicht mitgeben — der Server entfernt es automatisch. Bei Pfaden mit `/` wird `path=` verwendet