obsidian-mcp

MCP-Server, der das offizielle Obsidian-CLI umschließt, sodass ein LLM-Agent eine laufende Obsidian-Instanz steuern kann – Notizen lesen/schreiben, suchen, Frontmatter verwalten, Links navigieren, Plugins ausführen und mehr.

Dieser Server ist ein schlanker, umfassender Wrapper. Jedes Tool entspricht 1:1 einem obsidian-CLI-Befehl.

Voraussetzungen

1. Obsidian muss laufen. Das CLI kommuniziert über IPC mit der laufenden App; es liest den Vault nicht direkt von der Festplatte.

2. Registrieren Sie das CLI-Binary. In Obsidian: Einstellungen → Allgemein → Befehlszeilenschnittstelle → CLI registrieren. Obsidian fügt obsidian zu Ihrem PATH hinzu.

3. Überprüfung: obsidian version gibt die CLI-Version aus.

Installation

Zwei Wege, je nachdem, ob Sie es selbst bauen oder eine vorveröffentlichte Version von npm beziehen möchten.

Option A — Klonen & bauen (funktioniert sofort)

Klonen Sie das Repo und bauen Sie es lokal, dann verweisen Sie Claude Code auf die gebaute Datei:

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

Registrieren Sie es bei Claude Code (ein Befehl):

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user registriert es für Ihr gesamtes Benutzerkonto. Verwenden Sie -s project, um es stattdessen in die .mcp.json des Repos zu committen, oder -s local nur für das aktuelle Projekt (Standard).

Oder schreiben Sie es manuell in die .mcp.json:

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

Option B — Installation von npm (kein Build erforderlich)

Voraussetzung: Das Paket muss bereits auf npm veröffentlicht sein. Der Maintainer veröffentlicht einmal über npm publish; alle nachfolgenden Benutzer erhalten es automatisch über npx. Wenn Sie dieses Repo geforkt haben und diesen Ablauf unter Ihrem eigenen Scope wünschen, ändern Sie name in package.json zu @<ihr-npm-benutzername>/obsidian-mcp, dann npm publish.

Sobald veröffentlicht, ist kein Klonen oder Bauen erforderlich:

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

Oder in .mcp.json / claude_desktop_config.json von Claude Desktop:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

Überschreiben des CLI-Pfads

Wenn obsidian nicht im PATH ist, setzen Sie die Umgebungsvariable OBSIDIAN_CLI. Funktioniert mit beiden Installationspfaden:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

Tools

Vault & Dateien

Frontmatter-Eigenschaften

Suche

Tags & Links

Tägliche Notizen

Plugins

Entwickler / Erweitert

Meta

Konventionen

• Ziel einer Notiz — Tools, die auf Dateien abzielen, akzeptieren entweder:

  • file — Notizname im Wikilink-Stil (z. B. "Meine Notiz"), oder

  • path — Vault-relativer Dateipfad (z. B. "Ordner/Meine Notiz.md").

• Multi-Vault-Setups — Jedes Tool akzeptiert einen optionalen vault-Parameter. Wenn weggelassen, wird der zuletzt fokussierte Vault verwendet.

• Ausgabeformat — Listen-/Such-/Metadaten-Tools verwenden standardmäßig JSON für einfaches maschinelles Parsen.

Sensible Operationen & Benutzerbestätigung

Die folgenden Tools sind durch einen Benutzerbestätigungsschritt geschützt:

Wie der Schutz funktioniert:

1. MCP-Elicitation (bevorzugt). Wenn der verbundene Client die elicitation-Fähigkeit unterstützt (Claude Code tut dies), sendet der Server eine elicitation/create-Anfrage und der Client zeigt dem Benutzer eine Fortfahren?-Aufforderung mit der Aktion und dem Ziel an. Nur accept + confirm: true fährt fort.

2. Expliziter confirm: true-Parameter. Das Eingabeschema jedes sensiblen Tools enthält ein optionales confirm: boolean. Das Übergeben von confirm: true überspringt die Elicitation-Aufforderung – verwenden Sie dies nur, wenn der Aufrufer bereits die Zustimmung des Benutzers eingeholt hat.

3. Ablehnungs-Fallback. Wenn der Client keine Elicitation unterstützt und confirm: true nicht bereitgestellt wurde, gibt das Tool ein isError-Ergebnis zurück, das die Aktion benennt und den Aufrufer anweist, es mit confirm: true erneut zu versuchen.

Bypass für Batch / Automatisierung

OBSIDIAN_MCP_AUTO_CONFIRM=1

Setzen Sie diese Umgebungsvariable (im env-Block Ihres MCP-Clients), um jede Bestätigungsaufforderung zu überspringen. Nur in vollständig vertrauenswürdigen Automatisierungskontexten verwenden.

Lange Inhalte & argv-Limits

Das Obsidian-CLI unterstützt (noch) nicht das Lesen von Parameterwerten von stdin oder aus Dateien – jeder Wert wird über die Befehlszeile übertragen. Das kollidiert mit Plattform-Limits:

Um sicher zu bleiben, stückelt der Server lange Schreibvorgänge automatisch:

Splits erfolgen nach Möglichkeit an Zeilengrenzen; zu lange einzelne Zeilen fallen auf UTF-8-sichere Zeichengrenzen zurück. Der wieder zusammengesetzte Inhalt ist byte-identisch mit dem Original.

Konfigurieren Sie den Byte-Schwellenwert pro Aufruf (Standard: 6.000 unter Windows, 100.000 anderswo):

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

Wenn ein Stück in der Mitte eines mehrteiligen Schreibvorgangs fehlschlägt, gibt der Server isError mit einer klaren Meldung zurück, die angibt, welche Stücke auf der Festplatte gelandet sind, damit der Aufrufer wiederherstellen kann.

Entwicklung

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

Funktionsweise

runObsidian() (src/exec.ts) maskiert Argumente für die Shell, ruft das obsidian-Binary über child_process.exec auf und parst stdout. Die meisten Lese-Tools fordern format=json an; Ergebnisse werden für Clients, die strukturierte Tool-Ausgaben konsumieren, in structuredContent geparst, während sie weiterhin eine Textdarstellung in content zurückgeben.

Die Tool-Registrierung befindet sich in src/tools.ts — das Hinzufügen eines neuen umschlossenen Befehls ist dort ein einzelner Eintrag.

Referenz

• Obsidian CLI: https://obsidian.md/help/cli

• MCP-Spezifikation: https://modelcontextprotocol.io