Lokale REST-API mit MCP

Geben Sie Ihren Skripten, Browsererweiterungen und KI-Agenten über eine sichere, authentifizierte REST-API einen direkten Zugang zu Ihrem Obsidian-Vault.

• Interaktive API-Dokumentation: https://coddingtonbear.github.io/obsidian-local-rest-api/

• Obsidian-Community-Seite: https://community.obsidian.md/plugins/obsidian-local-rest-api/

• Was Sie tun können

• Schnellstart

  • REST-API

  • MCP-Clients

    • Claude Code

    • Claude Desktop

    • Cursor

    • Andere Clients

• API-Übersicht

• Hinweise zum Patchen

  • Raw-Content-Modus

• Bestimmte Abschnitte ansprechen

• Suchen

• MCP (Model Context Protocol)

  • Protokollrevisionen

  • Client verbinden

  • Verfügbare Werkzeuge

  • Verfügbare Ressourcen

• API-Erweiterungen

  • Typisierte Erweiterungs-API

  • Bekannte Erweiterungen

• Mitwirken

• Danksagungen

Was Sie tun können

Greifen Sie über die REST-API oder den integrierten MCP-Server auf Ihren Vault zu – beide Schnittstellen bieten dieselben Kernfunktionen, sodass Skripte, Browsererweiterungen und KI-Agenten dieselbe Sprache sprechen.

• Notizen lesen, erstellen, aktualisieren oder löschen – vollständiges CRUD für jede Datei in Ihrem Vault, einschließlich Binärdateien

• Bestimmte Abschnitte chirurgisch patchen – eine Überschrift, einen Blockverweis oder einen Frontmatter-Schlüssel ansprechen und nur diesen Abschnitt anhängen, voranstellen, ersetzen, löschen oder verschieben, ohne den Rest der Datei zu berühren

• Ihren Vault durchsuchen – einfache Volltextsuche oder strukturierte JsonLogic-Abfragen gegen Notizmetadaten (Frontmatter, Tags, Pfad, Inhalt)

• Auf die aktive Datei zugreifen – die aktuell in Obsidian geöffnete Notiz lesen oder schreiben

• Befehle auflisten und ausführen – jeden Obsidian-Befehl auslösen, als hätten Sie die Befehlspalette verwendet

• Tags abfragen – alle Tags in Ihrem Vault mit Nutzungszahlen auflisten

• Dateien in Obsidian öffnen – Obsidian anweisen, eine bestimmte Notiz in seiner Benutzeroberfläche zu öffnen

• Die API erweitern – andere Plugins können über die API-Erweiterungsschnittstelle eigene Routen registrieren

Alle Anfragen werden über HTTPS mit einem selbstsignierten Zertifikat bedient und durch die Authentifizierung mit einem API-Schlüssel geschützt.

Related MCP server: Connect MCP

Schnellstart

Nach der Installation und Aktivierung des Plugins öffnen Sie Einstellungen → Local REST API, um Ihren API-Schlüssel und Ihr Zertifikat zu finden.

REST-API

# Check the server is running (no auth required)
curl -k https://127.0.0.1:27124/

# List files at the root of your vault
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/

# Read a note
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md

# Read a specific heading (URL-embedded target)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append a line to a specific heading (PATCH with a JSON instruction)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Um Zertifikatswarnungen zu vermeiden, können Sie das Zertifikat von https://127.0.0.1:27124/obsidian-local-rest-api.crt herunterladen und vertrauen, oder Ihren HTTP-Client direkt darauf verweisen.

MCP-Clients

Der MCP-Server läuft unter https://127.0.0.1:27124/mcp/ und erfordert, dass Sie Ihr Bearer-Token zur Authentifizierung über einen Authorization-Header angeben (d. h. Authorization: Bearer <your-api-key>). Da das Plugin ein selbstsigniertes Zertifikat verwendet, müssen Sie möglicherweise entweder dem Zertifikat in Ihrem Betriebssystem/Client vertrauen oder den einfachen HTTP-Endpunkt unter http://127.0.0.1:27123/mcp/ verwenden (aktivieren Sie ihn unter Einstellungen → Local REST API → HTTP-Server aktivieren).

Claude Code

Claude Code bietet native HTTP-MCP-Unterstützung. Der schnellste Weg, den Server hinzuzufügen, ist über die CLI:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

Oder fügen Sie es manuell zu .mcp.json in Ihrem Projektstamm hinzu (projektbezogen) oder konfigurieren Sie es benutzerweit über claude mcp add --scope user:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Desktop

Claude Desktop unterstützt keine entfernten HTTP-MCP-Server nativ, aber Sie können es mit mcp-remote überbrücken (erfordert Node.js). Fügen Sie Folgendes zu claude_desktop_config.json hinzu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://127.0.0.1:27124/mcp/",
        "--header",
        "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

Starten Sie Claude Desktop nach dem Speichern der Datei neu.

Cursor

Cursor unterstützt den Streamable-HTTP-MCP-Transport. Fügen Sie Folgendes zu ~/.cursor/mcp.json (global) oder .cursor/mcp.json (projektspezifisch) hinzu:

{
  "mcpServers": {
    "obsidian": {
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Andere Clients

Jeder MCP-Client, der den Streamable-HTTP-Transport unterstützt, kann sich mit einem Authorization: Bearer <your-api-key>-Header mit https://127.0.0.1:27124/mcp/ verbinden. Konsultieren Sie die Dokumentation Ihres Clients für das genaue Konfigurationsformat.

API-Übersicht

Vollständige Details zu Anfragen/Antworten finden Sie in der interaktiven Dokumentation.

Hinweise zum Patchen

Die PATCH-Methode ist eine der nützlichsten Funktionen dieser API. Sie ermöglicht gezielte Änderungen, ohne ganze Dateien neu zu schreiben.

Senden Sie eine JSON-Anweisung: eine Operation (replace, prepend, append oder delete), die auf einen Geltungsbereich (content, marker, markerAndContent oder parent) eines Ziels angewendet wird – eine Überschrift (als Array von Überschriftentexten von der obersten Ebene abwärts adressiert), einen Blockverweis oder einen Frontmatter-Schlüssel. Die Nutzlast befindet sich in content (ein String), value (JSON, für Frontmatter-Werte) oder destination (eine Überschriftsverschiebung):

# Replace the value of a frontmatter field
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"frontmatter","target":"status","operation":"replace","value":"done"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Überschriftenebenen innerhalb eines content-Strings sind relativ zum Ziel (ein führendes # wird zu einem direkten Kind). Hinweiswarnungen (z. B. eine über Ebene 6 hinaus verschobene Überschrift) werden als prozentkodiertes JSON im Markdown-Patch-Warnings-Antwortheader zurückgegeben – dekodieren Sie mit decodeURIComponent, bevor Sie parsen. Übergeben Sie ifMatch (die version aus einer Dokumentkarte) für optimistische Nebenläufigkeit.

Hinweis: Leerraum gehört der Bibliothek – Ihr Inhalt wird auf getrimmte, kanonische Form reduziert (führende und abschließende Leerzeilen sind bedeutungslos), und die API selbst liefert die Leerzeile, wo immer eingefügter Inhalt auf Fließtext trifft, sodass ein append oder prepend immer als eigener Block landet und nie in einen bestehenden Absatz übergeht. Überschriftenzeilen, vorhandene Leerzeilen und der Abstandsstil jedes Dokuments bleiben unverändert. Beispiele finden Sie in der interaktiven Dokumentation.

Um einen vorhandenen Block fortzusetzen, statt einen neuen zu beginnen – etwa eine Liste zu erweitern – fügen Sie within zu einer Überschriftsanweisung hinzu: ein Index, der einen der obersten Textblöcke des Abschnitts auswählt (0-basiert in Dokumentreihenfolge, negativ vom Ende gezählt, also ist -1 der letzte Block). Eine within-Bearbeitung fügt wörtlich ein, sodass Sie die Verbindungsstelle selbst gestalten:

# Add an item to the last list under "Log" (the leading \n continues the block)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["Log"],"within":-1,"operation":"append","content":"\n- new item"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Mit dem Geltungsbereich markerAndContent fügen prepend/append stattdessen einen neuen Block neben dem indizierten ein. Indizes sind positionsbasiert, lesen Sie also zuerst die Dokumentkarte und kombinieren Sie die Bearbeitung mit ifMatch.

Raw-Content-Modus

Wenn Ihr Client Markdown in den Anforderungstext einfügt (Shortcuts, Tasker, curl aus einer Vorlage), ist das JSON-Escapen dieses Inhalts in eine Anweisung fragil. Der Raw-Content-Modus verschiebt die Felder der Anweisung aus dem Textkörper – Ziel in der URL (oder in Target-Type/Target-Headern mit explizitem Markdown-Patch-Version: 2), Operation und Optionen in Headern – und der Textkörper ist die rohe Nutzlast, kein JSON-Escaping erforderlich:

# Append a templated line under a heading — no JSON escaping anywhere
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Operation: append" \
  -H "Content-Type: text/markdown" \
  --data "- $TEMPLATED_CONTENT" \
  https://127.0.0.1:27124/vault/notes/daily.md/heading/Log

Ein text/*-Textkörper ist der content-Träger, ein application/json-Textkörper der value-Träger, und gar kein Textkörper trägt nichts (ein delete oder eine Verschiebung über einen Destination-Header). Target-Scope, Within (der within-Index der Anweisung als einfache Ganzzahl, z. B. -1), Create-Target-If-Missing, Reject-If-Content-Preexists und If-Match-Header vervollständigen die Anweisung. Siehe die interaktive Dokumentation für die Header-Kodierungen und die vollständigen Details.

Verwenden Sie bereits das ältere headerbasierte PATCH-Format? Es verteilte die Anweisung über Anforderungsheader statt über einen JSON-Textkörper und ist veraltet und wird in 6.0 entfernt. Es funktioniert weiterhin – senden Sie Markdown-Patch-Version: 1, um es wieder zu aktivieren (derselbe Header wählt auch die veraltete ::-verbundene Dokumentkarte bei GET aus), und Antworten, die darüber bedient werden, tragen einen Deprecation: true; sunset-version="6.0"-Header. Um zu aktualisieren, entfernen Sie diesen Header und verschieben Sie jeden Header in den JSON-Textkörper; die interaktive Dokumentation enthält die feldweise Zuordnungstabelle.

Siehe die interaktive Dokumentation für das vollständige Anweisungsschema und die Optionen.

Bestimmte Abschnitte ansprechen

Sie können einen bestimmten Teil einer Notiz lesen oder schreiben – eine Überschrift, einen Blockverweis oder ein Frontmatter-Feld – ohne die gesamte Datei abzurufen oder zu ersetzen. Dies funktioniert bei GET-, PUT-, POST- und PATCH-Anfragen (für PATCH ist dies der Raw-Content-Modus – fügen Sie einen Operation-Header hinzu).

Hängen Sie /<target-type>/<target> nach dem Dateinamen an. Jede verschachtelte Überschriftenebene ist ein eigenes Pfadsegment, sodass eine Überschrift, deren Text :: enthält, kein Escaping benötigt:

# Read the content under a specific heading
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Read a nested heading (one path segment per level)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/Work/Meetings

# Read a frontmatter field
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/frontmatter/status

# Replace the content of a heading via PUT (heading levels are normalized for you)
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append to a heading via POST
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Appended content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

Unterstützte Zieltypen: heading, block, frontmatter.

Bei einem GET wählt ein Target-Scope-Header aus, welcher Teil des Ziels zurückkommt, und spiegelt die PATCH-Geltungsbereiche: content (Standard), marker (das Label – der rohe Text einer Überschrift, die nackte ID eines Blocks, ein Frontmatter-Schlüssel) oder markerAndContent (der gesamte Knoten, genau in der Form, die ein PATCH replace in diesem Geltungsbereich verbraucht – ein Überschriftsunterbaum liest sich mit seiner eigenen Zeile als # Titel, Ebenen relativ zu seinem Elternteil):

# Read a whole section — heading line included — ready to edit and write back
curl -k -H "Authorization: Bearer <your-api-key>" \
  -H "Target-Scope: markerAndContent" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

Veraltet: headerbasiertes Targeting. Frühere Versionen sprachen einen Abschnitt mit Target-Type, Target und Target-Delimiter-Headern an (plus Target-Scope/Trim-Target-Whitespace). Diese Form ist veraltet und wird in 6.0 entfernt; sie wird nur verarbeitet, wenn Sie auch Markdown-Patch-Version: 1 senden (Antworten tragen dann einen Deprecation-Header). Ohne diesen wird die Bereitstellung dieser Targeting-Header mit 400 abgelehnt. Die gleichzeitige Bereitstellung von URL-Pfad-Targeting und der Header-Form in einer Anfrage gibt 422 Unprocessable Entity zurück.

Suchen

POST /search/simple/?query=your+terms führt die integrierte Fuzzy-Suche von Obsidian aus und gibt passende Dateinamen mit bewerteten Kontextausschnitten zurück.

POST /search/ akzeptiert einen JsonLogic-Ausdruck (Inhaltstyp application/vnd.olrapi.jsonlogic+json) und wertet ihn gegen die Metadaten jeder Notiz aus (Frontmatter, Tags, Pfad, Inhalt).

MCP (Model Context Protocol)

[!NOTE] Es gibt zwar mehrere MCP-Server von Drittanbietern für Obsidian, aber sie sind nicht mehr nötig – dieses Plugin enthält einen integrierten MCP-Server, der in Obsidian läuft und direkten Zugriff auf die Live-Metadaten deines Vaults, die aktive Datei und die Befehlspalette hat. Wenn du derzeit einen Server eines Drittanbieters verwendest, wirst du mit diesem wahrscheinlich bessere Ergebnisse erzielen.

Das Plugin enthält einen integrierten MCP-Server unter /mcp/, sodass KI-Agenten und MCP-kompatible Clients ohne manuell erstellte HTTP-Anfragen mit deinem Vault interagieren können.

Transport: Streamable HTTP – API-Schlüssel-Authentifizierung erforderlich.

Protokollrevisionen

Der Endpunkt bedient die Revision 2026-07-28 sowie die sitzungsbasierten Revisionen von 2024-10-07 bis 2025-11-25 und wählt pro Anfrage aus, sodass Clients beider Varianten ihn gemeinsam nutzen können.

Die Revision 2026-07-28 ist zustandslos: Es gibt keinen initialize-Handshake und keine Sitzung, daher sendet das Plugin den Mcp-Session-Id-Header weder aus noch liest es ihn. Jede Anfrage trägt ihre eigene Protokollversion und Client-Identität in params._meta, wiederholt sie in den Headern MCP-Protocol-Version, Mcp-Method und Mcp-Name und wird eigenständig beantwortet. Clients können server/discover aufrufen, um sich im Voraus über die unterstützten Revisionen und Fähigkeiten zu informieren.

Clients, die mit einer initialize-Anfrage beginnen, erhalten die sitzungsbasierte Revision, die sie aushandeln: Der Handshake gibt eine Mcp-Session-Id zurück, GET /mcp/ öffnet den Benachrichtigungsstream dieser Sitzung und DELETE /mcp/ beendet ihn. Sitzungen existieren nur auf diesem Pfad und sind es, die die listChanged-Fähigkeiten des Handshakes glaubwürdig halten: Wenn ein anderes Plugin ein MCP-Tool registriert oder entfernt, wird jede aktive Sitzung benachrichtigt, während Clients der Revision 2026-07-28 davon über einen subscriptions/listen-Stream erfahren.

Verbinden eines Clients

Verbinde deinen MCP-Client mit https://127.0.0.1:27124/mcp/. Die Authentifizierung verwendet ein Bearer-Token – finde deinen API-Schlüssel unter Einstellungen → Local REST API und übergebe ihn wie folgt:

Authorization: Bearer <your-api-key>

Die genaue Konfigurationssyntax variiert je nach Client; siehe die Beispiele unter Schnellstart oben oder konsultiere die Dokumentation deines Clients für entfernte Streamable-HTTP-MCP-Server.

[!WARNUNG] Für eine sichere Verbindung zum MCP-Server muss dein Client dem selbstsignierten Zertifikat des Plugins vertrauen. Du kannst es von https://127.0.0.1:27124/obsidian-local-rest-api.crt herunterladen und als vertrauenswürdig einstufen oder deinen Client so konfigurieren, dass die TLS-Überprüfung für 127.0.0.1 übersprungen wird.

Falls das Vertrauen in ein selbstsigniertes Zertifikat in deiner Umgebung nicht möglich ist, kannst du unsicher über http://127.0.0.1:27123/mcp/ statt https://127.0.0.1:27124/mcp/ verbinden, sofern du den HTTP-Endpunkt unter Einstellungen → Local REST API → HTTP-Server aktivieren aktiviert hast.

Verfügbare Tools

Verfügbare Ressourcen

API-Erweiterungen

Andere Plugins können eigene authentifizierte Routen, öffentliche Routen und MCP-Tools gegen den Server dieses Plugins registrieren. Eine Schritt-für-Schritt-Anleitung findest du unter Adding your own API Routes via an Extension.

Typisierte Erweiterungs-API

Installiere dieses Paket als Entwicklungsabhängigkeit, um getAPI und die Typen für alles, was es zurückgibt, zu erhalten:

npm install --save-dev obsidian-local-rest-api

Dieses Paket deklariert obsidian, zod und @types/express als Peer-Abhängigkeiten, da seine Typen auf alle drei verweisen – addRoute gibt express' IRoute zurück und addMcpTool akzeptiert zod-Schemas. npm installiert Peer-Abhängigkeiten für dich; wenn du sie selbst festlegst, halte sie auflösbar. Ohne sie erweitert TypeScript diese Positionen stillschweigend auf any, statt einen Fehler zu melden. Ein Projekt, das die Diagnose für fehlende Typen unterdrückt, erhält daher keine Warnung, dass es die Typprüfung genau dort verloren hat, wo sie am wichtigsten ist.

import { getAPI, type LocalRestApiPublicApi } from "obsidian-local-rest-api";

const api: LocalRestApiPublicApi | undefined = getAPI(this.app, this.manifest, 2);

Der Einstiegspunkt des Pakets ist ein kleines eigenständiges Modul – es löst das laufende Host-Plugin aus Obsidians Plugin-Registry auf, statt das Plugin-Bundle in deinen Build einzubinden. Wenn du eine Erweiterungs-API-Version übergibst (2 oben), lässt getAPI ApiVersionUnsupportedError auslösen, wenn der installierte Host älter ist als die Oberfläche, die du benötigst; lasse sie weg, um zu akzeptieren, was installiert ist, und selbst Feature-Erkennung durchzuführen. getAPI gibt undefined zurück, wenn das Plugin nicht installiert ist oder noch nicht geladen wurde.

publicApi.d.ts wird aus src/publicApi.ts generiert, gegen das die Implementierung zur Kompilierzeit geprüft wird, sodass die veröffentlichten Typen nicht von dem abweichen können, was das Plugin tatsächlich bietet.

Bekannte Erweiterungen

• Periodic Notes: Fügt Unterstützung für periodische Notizen hinzu

Mitwirken

Siehe CONTRIBUTING.md. Wenn du Funktionalität hinzufügen möchtest, ohne den Kern zu verändern, erwäge stattdessen, eine API-Erweiterung zu bauen – Erweiterungen können unabhängig entwickelt und veröffentlicht werden.

Danksagungen

Inspiriert von Vinzent03s advanced-uri-Plugin, mit dem Ziel, die Automatisierungsmöglichkeiten über die Grenzen benutzerdefinierter URL-Schemata hinaus zu erweitern.