obsidian-mcp-server

[!NOTE] Dieses Repository ist die huaqing0 custom edition, basierend auf cyanheads/obsidian-mcp-server v3.5.0 unter der Apache-2.0-Lizenz. Es bewahrt den Upstream-Server und fügt den lokalen Arbeitsbereich, die Vault-Struktur und die native Excalidraw-Automatisierung hinzu, die in dieser Edition verwendet werden. Die npm- und MCPB-Installationslinks unten verweisen weiterhin auf die Upstream-Distribution; diese Custom Edition ist derzeit nur als Quellcode verfügbar.

Werkzeuge

Einunddreißig Werkzeuge decken Notizinhalt, Metadaten, Backlinks, native Excalidraw-Automatisierung und die vollständige Verwaltung der Vault-Struktur ab, plus einen geschützten Notausstieg für Obsidian-Befehlspaletten-Befehle.

obsidian_get_note

Eine Notiz in einer von vier Projektionen lesen, adressiert über Vault-Pfad, die aktive Datei oder eine periodische Notiz (daily, weekly, monthly, quarterly, yearly).

• format: "content" — roher Markdown-Textkörper

• format: "full" — Inhalt, Frontmatter, Tags und Dateimetadaten; includeLinks: true übergeben, um geschriebene ausgehende Referenzen sowie von Obsidian aufgelöste ausgehende Links und Backlinks einzuschließen (nur vault-intern — externe URLs werden herausgefiltert)

• format: "document-map" — Katalog von Überschriften, Blockverweisen und Frontmatter-Feldern

• format: "section" — einzelner Überschriften-/Block-/Frontmatter-Abschnittswert (erfordert section); Überschriftenabschnitte umfassen den vollständigen Unterbaum unter dieser Überschrift

Die Dokumentkarten-Projektion mit obsidian_patch_note kombinieren, um Bearbeitungsziele vor dem Patchen zu entdecken.

obsidian_search_notes

Bis zu drei Suchmodi, ausgewählt über mode:

• text — Teilstring-Übereinstimmung mit umgebenden Kontextfenstern. contextLength steuert die Zeichen des Kontexts pro Seite jeder Übereinstimmung (Standard 100; erhöhen für mehr Kontext pro Treffer). Optionaler pathPrefix-Filter (nur Textmodus — die Übergabe von pathPrefix in jedem anderen Modus wird mit path_prefix_invalid_mode abgelehnt).

• jsonlogic — JSONLogic-Baum, ausgewertet gegen path, content, frontmatter.<key>, tags und stat.{ctime,mtime,size}; benutzerdefinierte glob- und regexp-Operatoren, die beide [PATTERN, VALUE] annehmen — zuerst das Muster, dann die Feldreferenz: {"glob": ["Projects/*.md", {"var": "path"}]}. Die umgekehrte Reihenfolge kompiliert das eigene Feld der Notiz als Muster: glob stimmt dann mit nichts überein, und regexp schlägt sofort fehl, egal was das Feld ergibt. So werden auch Backlinks ausgedrückt, da es kein dediziertes Tool oder Upstream-Endpoint dafür gibt: {"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]} gibt jede Notiz zurück, deren Textkörper per Wikilink auf Target Note verweist.

• omnisearch — BM25-bewertete Suche über das Community-Plugin Omnisearch. Unterstützt in Anführungszeichen gesetzte Phrasen, -exclusion, path: / ext:-Filter, Tippfehlertoleranz, PDF- + OCR-Abdeckung (über Text Extractor) und visuelle Konzept-Bildübereinstimmungen, wenn die Indizierung von AI Image Analyzer aktiviert ist. Nur im Modus-Enum vorhanden, wenn der HTTP-Server des Plugins beim Start erreichbar ist; der Upstream begrenzt Ergebnisse hart auf 50 — die Abfrage eingrenzen, um mehr sichtbar zu machen (die Antwort enthält truncated: true, wenn die Obergrenze wahrscheinlich erreicht wurde).

Die Ergebnisse werden gemäß der MCP-2025-11-25-Spezifikation über undurchsichtige Cursor paginiert: Lassen Sie cursor für die erste Seite weg und übergeben Sie dann nextCursor aus der vorherigen Antwort. Jedes Ergebnis enthält totalCount (nach Pfadrichtlinie, vor Paginierung); nextCursor wird auf der letzten Seite weggelassen. Treffer im Textmodus werden zusätzlich pro Datei auf maxMatchesPerHit (Standard 10) begrenzt, damit eine einzelne trefferlastige Notiz das Antwortbudget nicht sprengen kann – abgeschnittene Treffer tragen truncated: true und totalMatches.

obsidian_write_note

Erstellen oder chirurgisch ersetzen, mit einem schützenden Standard gegen versehentliches Überschreiben ganzer Dateien.

• Ohne section – vollständiges PUT der Datei. Weigert sich, eine vorhandene Datei zu überschreiben, es sei denn, overwrite: true ist gesetzt. Der Fehler file_exists (Conflict) schlägt obsidian_patch_note / obsidian_append_to_note / obsidian_replace_in_note für In-Place-Bearbeitungen vor.

• Mit section – PATCH-mit-Ersetzen gegen die benannte Überschrift/den Block/das Frontmatter-Feld, wobei der Rest der Datei unberührt bleibt. Das Flag overwrite wird im Abschnittsmodus ignoriert.

Die Ausgabe meldet created: true, wenn der Aufruf eine neue Datei ins Leben gerufen hat; false, wenn eine vorhandene Datei ersetzt oder ein Abschnitt angezielt wurde. Jedes mutierende Tool gibt außerdem previousSizeInBytes und currentSizeInBytes zurück, damit ein Agent versehentliche Überschreibungen, unerwartetes Upstream-Verhalten oder einen Tippfehlerpfad erkennen kann, der bei der falschen Datei gelandet ist.

obsidian_append_to_note

Ein kombiniertes Upsert- und Abschnitt-Anhängen-Primitiv, das das Verhalten der lokalen REST-API des Upstreams widerspiegelt:

• Ohne section – POST an /vault/{path}. Hängt an, wenn die Datei existiert, erstellt die Datei mit Ihrem Inhalt als gesamten Textkörper, wenn sie nicht existiert. Das created: true der Ausgabe kennzeichnet den zweiten Zweig, damit der Agent bemerken kann, wenn ein Tippfehlerpfad oder eine noch nicht erstellte Tagesnotiz stillschweigend zu einer brandneuen Datei wurde.

• Mit section – PATCH-mit-Anhängen gegen die benannte Überschrift, den Blockverweis oder das Frontmatter-Feld. Die Datei muss existieren (sonst wirft der PATCH-Preflight note_missing). Setzen Sie createTargetIfMissing: true, um den Abschnitt selbst in einer vorhandenen Datei ins Leben zu rufen. Blockverweis-Ziele verketten sich ohne Trennzeichen neben der Blockzeile – fügen Sie ein führendes Zeilenumbruchzeichen in content ein, wenn Sie eines möchten.

previousSizeInBytes ist 0 auf dem Upsert-Erstellen-Zweig und andernfalls die tatsächliche Dateigröße; currentSizeInBytes ist die nach dem Schreiben vom Upstream gelesene Größe. Vergleichen Sie Deltas mit Buffer.byteLength(content), um automatische Zeilenumbruch-Injektion oder gleichzeitige Schreiber zu erkennen.

obsidian_patch_note

Chirurgische Bearbeitungen an einem einzelnen Dokumentziel.

• operation: "append" fügt nach dem Abschnitt hinzu

• operation: "prepend" fügt vor dem Abschnitt hinzu

• operation: "replace" tauscht ihn aus

• Ziele: Überschriftspfad, Blockverweis-ID oder Frontmatter-Feld

Überschriftziele akzeptieren entweder den vollständigen Parent::Child-Pfad oder einen bloßen Blattnamen. Ein bloßes Blatt, das genau einer Überschrift entspricht, wird vor dem Schreiben zu seinem vollständigen Pfad erweitert, und die Antwort gibt den Locator zurück, auf dem die Bearbeitung gelandet ist; ein Blatt, das mehreren Überschriften entspricht, wird mit ambiguous_section abgelehnt, dessen Fehlerdaten die Kandidatenpfade auflisten. Dieselbe Auflösung gilt für obsidian_write_note und obsidian_append_to_note mit section.

Verwenden Sie obsidian_get_note mit format: "document-map", um zu entdecken, welche Ziele vor dem Patchen existieren.

obsidian_replace_in_note

Suchen-und-Ersetzen für Bearbeitungen, die nicht zu den strukturellen Zielen von obsidian_patch_note passen. Die Notiz wird abgerufen, Ersetzungen werden sequenziell angewendet (jede sieht die vorherige Ausgabe), und das Ergebnis wird in einem einzigen PUT zurückgeschrieben.

scope wählt aus, worüber die Ersetzungen laufen:

• body (Standard) – der Text nach dem YAML-Frontmatter-Block. Der Block wird aus den ursprünglichen Bytes wieder angehängt, sodass er byte-identisch zurückkommt.

• frontmatter – nur das YAML zwischen den ----Begrenzern. Die Begrenzer selbst werden nie abgeglichen.

• both – jede Ersetzung läuft über das Frontmatter und dann über den Textkörper; perReplacement[] meldet bodyCount und frontmatterCount getrennt.

Mit dem Frontmatter im Geltungsbereich wird das umgeschriebene YAML vor dem Schreiben erneut geparst: Wenn es nicht mehr als Zuordnung von Eigenschaften parst, schlägt der Aufruf mit frontmatter_invalid fehl und die Notiz behält ihre ursprünglichen Bytes. Diese Prüfung fängt YAML, das bricht – ein nicht in Anführungszeichen gesetztes : in einem Skalar, ein Listenmarker, der in einen Alias umgeschrieben wurde, ein verirrtes Anführungszeichen. Sie kann keine Bearbeitung fangen, die wohlgeformt bleibt, während sie etwas anderes bedeutet, wie eine Teilzeichenfolgen-Kollision, die einen Schlüssel umbenennt, oder eine Ersetzung, die die Anführungszeichen eines Skalars entfernt und seinen Typ ändert. Bevorzugen Sie obsidian_manage_frontmatter für typisierte Bearbeitungen einer einzelnen Eigenschaft.

Optionen pro Ersetzung:

• useRegex – behandelt search als ECMAScript-Regex. Mit useRegex: true berücksichtigt die Ersetzung $1 / $&-Erfassungsgruppen-Referenzen.

• caseSensitive – bei false wird ohne Beachtung der Groß-/Kleinschreibung abgeglichen

• wholeWord – umschließt das Muster mit \b…\b; funktioniert sowohl im Literal- als auch im Regex-Modus

• flexibleWhitespace – ersetzt jede Folge von Leerzeichen in search durch \s+. Nur Literal-Modus – hat keine Wirkung, wenn useRegex: true ist (drücken Sie es direkt aus).

• replaceAll – bei false wird nur der erste Treffer ersetzt. Unter scope: 'both' geht diese eine Ersetzung an das Frontmatter, wenn sie dort übereinstimmt, und andernfalls an den Textkörper.

Der Literal-Modus bewahrt $1 / $& in der Ersetzung wörtlich – nur useRegex: true expandiert Erfassungsgruppen-Referenzen.

obsidian_manage_tags

Tags zu einer Notiz hinzufügen, entfernen oder auflisten. Arbeitet mit einer von zwei Darstellungen, standardmäßig mit dem kanonischen Obsidian-Frontmatter-Ort:

• location: 'frontmatter' (Standard) – nur das tags:-Array im Frontmatter; der Notiztext bleibt unberührt

• location: 'inline' – nur Inline-#tag-Syntax im Textkörper; add hängt #tag am Dateiende an

• location: 'both' – opt-in Abgleich über beide Darstellungen

add stellt sicher, dass das Tag an den angeforderten Orten vorhanden ist; remove entfernt es; list ignoriert das Eingabe-tags-Array. Inline-#tag-Vorkommen innerhalb von Codeblöcken mit Begrenzern werden absichtlich unberührt gelassen.

Der Inline-Modus liest und schreibt nur den Notiztext – ein # innerhalb eines YAML-Skalars ist Frontmatter, wird also weder als Inline-Tag aufgelistet noch durch eine Entfernung umgeschrieben. Das Entfernen eines Inline-Tags nimmt genau ein angrenzendes horizontales Leerzeichen mit – das vor dem Tag oder das danach, wenn kein Leerzeichen davor steht; jedes andere Byte überlebt, einschließlich verschachtelter Listeneinrückung, um vier Leerzeichen eingerückter Codeblöcke, nachgestellter harter Zeilenumbrüche mit zwei Leerzeichen und Tabellenzellen-Padding.

obsidian_delete_note

Eine Notiz dauerhaft löschen. Standardmäßig deaktiviert. Setzen Sie OBSIDIAN_ENABLE_DELETE=true, um sie in tools/list verfügbar zu machen. Der erste Aufruf antwortet mit einer Bestätigungsanfrage statt einer Löschung – die Eingabeaufforderung enthält die Bytegröße der Datei, sodass der zerstörerische Wirkungsradius sichtbar ist, bevor der Benutzer bestätigt – und das Tool wird mit der Antwort erneut versucht. Ablehnen oder Abbrechen schlägt den Aufruf mit cancelled fehl und gibt kein DELETE aus; die destructiveHint-Annotation macht die Operation auch im Genehmigungsablauf des Hosts sichtbar. Die Ausgabe meldet previousSizeInBytes (Größe im Moment der Löschung) und currentSizeInBytes: 0.

Die Bestätigung ist nicht optional und hat keinen Fallback-Pfad: Ein Client, der den Eingabe-Roundtrip nicht bedienen kann, kann keine Löschung abschließen. Jedes andere Tool ist davon unberührt.

Vault-Struktur-Tools

obsidian_create_folder erstellt verschachtelte Ordner idempotent. obsidian_move_path verschiebt oder benennt entweder Dateien oder Ordner über den nativen FileManager von Obsidian um, erstellt fehlende Ziel-Eltern und erlaubt Obsidian, interne Links zu aktualisieren. obsidian_delete_folder entfernt einen Ordner rekursiv unter Verwendung des konfigurierten Papierkorb-Verhaltens von Obsidian standardmäßig oder dauerhaft, wenn explizit angefordert; es ist zusammen mit dem Löschen von Notizen durch OBSIDIAN_ENABLE_DELETE=true gesperrt.

obsidian_execute_command

Sendet einen Obsidian-Befehlspaletten-Befehl per ID (entdeckbar über obsidian_list_commands). Das Verhalten ist befehlsabhängig – einige Befehle öffnen die Benutzeroberfläche, andere löschen Dateien oder schließen den Vault.

Standardmäßig deaktiviert. Wenn OBSIDIAN_ENABLE_COMMANDS nicht gesetzt ist, werden sowohl obsidian_execute_command als auch sein Entdeckungspartner obsidian_list_commands mit disabledTool() umschlossen – abwesend aus tools/list (das LLM kann sie nicht aufrufen), aber weiterhin im bedienerorientierten Manifest mit einem Hinweis sichtbar, sie zu aktivieren.

Related MCP server: Obsidian Tools MCP Server

Pfadrichtlinie (ordnerbezogene Berechtigungen)

Drei optionale Umgebungsvariablen steuern, welche Vault-Pfade jedes Tool anzielen kann. Standard nicht gesetzt = voller Vault für sowohl Lese- als auch Schreibvorgänge – abwärtskompatibel.

Der Abgleich ist präfixbasiert mit impliziter Rekursion, ohne Beachtung der Groß-/Kleinschreibung, mit normalisierten nachgestellten Schrägstrichen. projects/ passt auf projects/a.md, projects/sub/b.md usw.

Schreibpfade sind implizit lesbar – Sie können nicht sinnvoll bearbeiten, was Sie nicht sehen können. Ein Lesevorgang besteht also, wenn das Ziel mit READ_PATHS oder WRITE_PATHS übereinstimmt.

OBSIDIAN_READ_ONLY=true greift vor den Pfadprüfungen – jedes Schreib-Tool und das Befehlspaletten-Paar werden beim Start mit disabledTool() umschlossen (abwesend aus tools/list), und jeder Schreibvorgang, der den Dienst dennoch erreicht, wird zur Laufzeit unabhängig von WRITE_PATHS verweigert.

Ablehnungen sind als path_forbidden (JSON-RPC-Code Forbidden) typisiert, wobei der aktive Geltungsbereich in data.recovery.hint und data.activeScope zurückgegeben wird, damit das LLM sich selbst korrigieren kann, ohne Serverprotokolle zu inspizieren. Suchergebnisse von obsidian_search_notes werden still gegen READ_PATHS gefiltert – das Anzeigen eines „wir haben N Treffer versteckt“-Indikators würde das Tor zunichtemachen.

Die Tag-Auflistung ist vaultweit. obsidian_list_tags und die Ressource obsidian://tags aggregieren Tag-Namen über den gesamten Vault und werden nicht durch OBSIDIAN_READ_PATHS eingeschränkt – sie nehmen keinen Pfad zum Sperren, sodass Tag-Namen (niemals Notizinhalte) von außerhalb des Lesebereichs auftauchen können.

Das Startbanner protokolliert den aktiven Geltungsbereich, damit Bediener ihre Konfiguration beim Booten überprüfen können.

Ressourcen

Alle Ressourcendaten sind auch über Tools erreichbar – obsidian_get_note für obsidian://vault/{+path}, obsidian_list_tags für obsidian://tags. Ressourcen existieren für Clients, die es bevorzugen, eine bestimmte Notiz oder einen Vault-Schnappschuss an ein Gespräch anzuhängen. Das Tag-Paar ist kein Spiegel: obsidian://tags behält Schnappschuss-Semantik und gibt die Upstream-Nutzlast ganz und unsortiert zurück, während obsidian_list_tags nach Anzahl ordnet und begrenzt.

Funktionen

Basiert auf @cyanheads/mcp-ts-core:

• Deklarative Tool- und Ressourcendefinitionen – eine Datei pro Primitive, das Framework übernimmt Registrierung und Validierung

• Einheitliche Fehlerbehandlung – Handler werfen, das Framework fängt, klassifiziert und formatiert. Tools geben ihre Fehlerfläche über typisierte errors[]-Verträge an.

• Server-Level-instructions bei initialize – zeigt bereitstellungsspezifische Orientierung (aktive Pfadrichtlinie, Nur-Lese-Modus, Command-Palette-Umschalter) neben dem statischen Tool-/Ressourcenkatalog für spezifikationskonforme Clients an.

• Plug-in-fähige Authentifizierung auf dem HTTP-Transport: none, jwt, oauth

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

• STDIO- und Streamable-HTTP-Transports

Der Server selbst ist zustandslos – jeder Tool-Aufruf trifft direkt auf die Local REST API. Die Speicher-Backends des Frameworks, Request-State-KV und Fortschritts-Streams werden hier nicht verwendet; Obsidian ist ein einzelner Vault und es gibt nichts, was zwischen Aufrufen persistiert werden müsste.

Obsidian-spezifisch:

• Kapselt das Obsidian Local REST API-Plugin – typisierter Client, deterministisches Fehler-Mapping

• Abschnittsbewusstes Bearbeiten über Überschriften, Blockreferenzen und Frontmatter-Felder mittels PATCH-mit-Ziel-Operationen

• Tag-Abgleich über beide Darstellungen: Frontmatter-tags:-Array und Inline-#tag-Syntax (unter Überspringen von Codeblöcken mit Begrenzern)

• Suche über bis zu drei Modi: Text, JSONLogic und (wenn das Plugin erreichbar ist) BM25-bewertete Omnisearch – cursor-paginiert gemäß MCP-2025-11-25-Spezifikation, mit Begrenzung der Treffer pro Datei im Textmodus

• Erforderliche Bestätigung durch einen Menschen für destruktive Löschungen – eine mehrstufige input_required-Runde, die in beiden Protokollrevisionen angeboten wird, ohne unbestätigten Pfad durch das Tool

• Native Verwaltung der Vault-Struktur: Ordner erstellen, Dateien oder Ordner mit Obsidian-Link-Updates verschieben/umbenennen und Ordner über den Papierkorb oder dauerhaft löschen

• Native Integration der Excalidraw Automation API: semantisches Erstellen/Lesen/Hinzufügen/Aktualisieren/Löschen, deterministisches Layout, Integritätsvalidierung, PNG-Vorschau-Export und idempotente Notiz-Einbettung

• Ordnerbezogene Lese-/Schreibberechtigungen über OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS und einen globalen OBSIDIAN_READ_ONLY-Kill-Switch – Ablehnungen sind als path_forbidden typisiert, wobei der aktive Geltungsbereich in den Fehlerdaten zurückgespiegelt wird

• Opt-in-Befehlspaletten-Paar (obsidian_list_commands + obsidian_execute_command) – nur registriert, wenn OBSIDIAN_ENABLE_COMMANDS=true

• Nachsichtige Pfadauflösung bei obsidian_get_note und obsidian_open_in_ui – versucht stillschweigend Pfade mit falscher Groß-/Kleinschreibung gegen den kanonischen Dateinamen, wirft Conflict bei mehrdeutigen Groß-/Kleinschreibungs-Treffern und reichert NotFound mit Meinten Sie: …?-Vorschlägen an, wenn nur nahe Treffer existieren. obsidian_delete_note ist bewusst ausgenommen – eine destruktive Operation sollte den Zielpfad nicht stillschweigend umschreiben.

Erste Schritte

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfigurationsdatei hinzu. Das Obsidian Local REST API Plugin muss in Ihrem Vault installiert und aktiviert sein – siehe Voraussetzungen.

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Oder mit npx (kein Bun erforderlich):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Für Streamable HTTP setzen Sie den Transport und starten Sie den Server. Inline-Umgebungsvariablen funktionieren für einmalige Ausführungen; für wiederholte Nutzung kopieren Sie Werte in .env (siehe .env.example) und führen Sie bun run start:http aus.

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
# Server listens at http://127.0.0.1:3010/mcp by default

Voraussetzungen

• Bun v1.3.0 oder höher (oder Node.js v24+).

• Das Obsidian Local REST API-Plugin, v4.0.0 bis v5.x, installiert und aktiviert in Ihrem Vault. Generieren Sie einen API-Schlüssel unter Einstellungen → Community-Plugins → Local REST API und kopieren Sie ihn in OBSIDIAN_API_KEY. Plugin v6.0 entfernt das Markdown-Patch-1.x-Wire-Format, das dieser Server für abschnittsgezielte Schreibvorgänge und die Dokumentkarte festlegt.

• Periodische Notiz-Ziele (target: { "type": "periodic" }) benötigen zusätzlich Plugin v5.0.1 oder früher – v5.0.2 hat die eingebauten /periodic/-Routen entfernt. Alle anderen Zieltypen sind nicht betroffen.

• Ein MCP-Client, der eine Eingabeanfrage (Elicitation) beantworten kann. obsidian_delete_note fragt vor dem Löschen immer nach Bestätigung, sodass ein Client ohne diese Unterstützung Notizen lesen und schreiben, aber keine löschen kann.

• Optional: das Obsidian Excalidraw-Plugin installiert und aktiviert, um die elf Zeichenwerkzeuge zu nutzen. Andere Notiz- und Vault-Tools benötigen es nicht.

• Dieser Server verwendet standardmäßig http://127.0.0.1:27123 der Einfachheit halber. Aktivieren Sie „Non-encrypted (HTTP) Server“ in den Plugin-Einstellungen, um ihn zu nutzen. Um stattdessen den immer aktiven HTTPS-Port zu verwenden, setzen Sie OBSIDIAN_BASE_URL=https://127.0.0.1:27124; das selbstsignierte Zertifikat des Plugins wird durch OBSIDIAN_VERIFY_SSL=false (Standard) behandelt.

Installation

1. Repository klonen:

   git clone https://github.com/cyanheads/obsidian-mcp-server.git

2. In das Verzeichnis wechseln:

   cd obsidian-mcp-server

3. Abhängigkeiten installieren:

   bun install

4. Umgebung konfigurieren:

   cp .env.example .env
   # edit .env and set OBSIDIAN_API_KEY

Konfiguration

Siehe .env.example für die vollständige Liste optionaler Überschreibungen.

Server ausführen

Lokale Entwicklung

• Produktionsversion erstellen und ausführen:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

• Prüfungen und Tests ausführen:

bun run devcheck   # Lint, format, typecheck, security, changelog sync
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t obsidian-mcp-server .
docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server

Das Dockerfile verwendet standardmäßig HTTP-Transport, zustandslosen Sitzungsmodus und protokolliert nach /var/log/obsidian-mcp-server. OpenTelemetry-Peer-Abhängigkeiten werden standardmäßig installiert — bauen Sie mit --build-arg OTEL_ENABLED=false, um sie wegzulassen.

Das Image bindet innerhalb des Containers an 0.0.0.0 (erforderlich für Docker-Portzuordnung). Für jede Bereitstellung, die über Ihre eigene Maschine hinaus erreichbar ist, setzen Sie MCP_AUTH_MODE=jwt (mit MCP_AUTH_SECRET_KEY) oder oauth – andernfalls leitet der Listener Ihre OBSIDIAN_API_KEY im Namen jedes Aufrufers an den Tresor weiter.

Projektstruktur

Entwicklungsleitfaden

Siehe CLAUDE.md für Entwicklungsrichtlinien und Architekturregeln. Die Kurzfassung:

• Handler werfen, Framework fängt – kein try/catch in der Tool-Logik

• Verwenden Sie ctx.log für anforderungsbezogenes Logging, ctx.state für mandantenbezogenen Speicher

• Registrieren Sie neue Tools und Ressourcen über die Barrels in src/mcp-server/*/definitions/index.ts

• Kapseln Sie externe API-Aufrufe: Rohdaten validieren → in Domänentyp normalisieren → Ausgabeschema zurückgeben; fehlende Felder niemals erfinden

Mitwirken

Fehler, Funktionsanfragen und Dokumentationslücken gehören in ein Issue – siehe CONTRIBUTING.md für das, was ein Issue umsetzbar macht, und CODE_OF_CONDUCT.md für unsere Zusammenarbeit. Sicherheitsmeldungen gehen über SECURITY.md, niemals über ein öffentliches Issue.

Pull Requests sind für kleine, in sich geschlossene Korrekturen willkommen. Führen Sie vor dem Einreichen Prüfungen und Tests aus:

bun run devcheck
bun run test

Lizenz

Apache-2.0 – siehe LICENSE für Details.