Obsidian MCP Server

obsidian-mcp-server ist ein MCP-Server, der es KI-Agenten ermöglicht, Markdown-Dokumente in einem Obsidian-Vault abzurufen, zu durchsuchen und zusammenzufassen.

Durch die Verbindung mit einem MCP-Client können Agenten den Inhalt des Vaults abrufen, während der Token-Verbrauch kontrolliert wird.

Was ist möglich?

• Stichwortbasierte Notizsuche (vault, action="search")

• Lesen einer bestimmten Notiz (vault, action="read")

• Auflisten aller Dokumente im Vault (vault, action="list_all")

• Abrufen des Vault-Status (vault, action="stats")

• Erstellen von Speicherpaketen für langfristigen Kontext (vault, action="collect_context")

• Laden gespeicherter Speicher-Notizen (vault, action="load_memory")

• Vorschläge zur automatischen Generierung von Frontmatter (generate_property)

• Tatsächliche Anwendung von Frontmatter (write_property)

• Dokumentbasierte Prompt-Workflows (create_document_with_properties)

• Organisation von Bildanhängen (organize_attachments)

Sicherheitshinweise

Dieser Server macht den Inhalt Ihres Vaults für den Client zugänglich. Gehen Sie in Produktionsumgebungen vorsichtig vor.

• Verbinden Sie sich nicht mit nicht vertrauenswürdigen KI-Agenten.

• Beschränken Sie den Vault-Pfad (VAULT_DIR_PATH) auf die minimal erforderlichen Berechtigungen.

• Kontrollieren Sie bei großen Vaults die Token-Kosten durch Anpassung von maxOutputChars und limit.

• Der Standard-Komprimierungsmodus für die vault-Aktion ist balanced.

Konfigurationshinweise

1. Vault-Pfad: Für VAULT_DIR_PATH muss zwingend ein absoluter Pfad angegeben werden.

// ✅ 올바른 예시
"VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
"VAULT_DIR_PATH": "C:\\Users\\username\\Documents\\MyVault"  // Windows
"VAULT_DIR_PATH": "/mnt/c/Users/username/Documents/MyVault"  // WSL

// ❌ 잘못된 예시
"VAULT_DIR_PATH": "~/Documents/MyVault"  // 상대 경로 사용 불가
"VAULT_DIR_PATH": "./vault"              // 상대 경로 사용 불가

2. Node.js-Anforderungen: Node.js 22 oder höher muss installiert sein.

node --version  # v22.0.0 이상 확인

Erste Schritte (Schnelleinrichtung)

1) Allgemeine Anforderungen

• Die Mindestkonfiguration ist VAULT_DIR_PATH (absoluter Pfad zum Vault).

• Die Ausführung des MCP erfolgt basierend auf dem Verteilungspaket:

  • Verwendung des Verteilungspakets (npx) (empfohlen)

  • Lokales build/index.js ist für Entwicklung/Debugging gedacht

• Die lokale Ausführung wird im letzten Abschnitt (5) separat erläutert.

• Wenn der Vault-Pfad fehlt, schlägt der Start fehl.

• Die folgenden Beispiele sind so aufbereitet, dass sie direkt kopiert und eingefügt werden können.

2) Verteilungspaket (npx) Konfiguration

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": {
        "VAULT_DIR_PATH": "/abs/path/to/your/vault",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

CLI-Direktausführung:

npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault --logging-level info

3) MCP-Client-Konfiguration

Auch wenn die Benutzeroberfläche je nach Client variiert, ist die Grundform von command/args/env identisch.

Kernpunkt für das Verteilungspaket: command="npx", args=["-y","@sunub/obsidian-mcp-server@latest"], env.VAULT_DIR_PATH

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "@sunub/obsidian-mcp-server@latest"]
env = { VAULT_DIR_PATH = "/abs/path/to/your/vault" }

1. copilot ausführen

2. /mcp add

3. Werte wie folgt eingeben:

• Server name: obsidian

• Server Type: [1] Local

• Command: npx -y @sunub/obsidian-mcp-server@latest

• Environment: { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }

Da die JSON-Schlüsselnamen je nach Version variieren können (z. B. servers/mcpServers), passen Sie dies bitte an Ihre Projektdokumentation an.

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
    }
  }
}

Registrieren Sie es unter Cursor Settings → MCP → New MCP Server.

{
  "obsidian": {
    "command": "npx",
    "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
    "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
  }
}

※ Bei einigen Versionen kann der Schlüsselname für die Server-Identifizierung abweichen; folgen Sie den Anweisungen auf dem Einstellungsbildschirm.

Beispiel für die Paketinstallation:

gemini mcp add obsidian npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault

※ Da einige Gemini-Versionen --vault-path möglicherweise anders unterstützen, prüfen Sie die aktuelle Dokumentation von gemini mcp add.

4) Beispiel für eine vollständige Konfiguration

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "@sunub/obsidian-mcp-server@latest"
      ],
      "env": {
        "VAULT_DIR_PATH": "/path/to/obsidian-vault",
        "VAULT_METRICS_LOG_PATH": "/path/to/vault-metrics.ndjson",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

Umgebungsvariablen

• VAULT_DIR_PATH (erforderlich): Absoluter Pfad zum Obsidian-Vault

• VAULT_METRICS_LOG_PATH (optional): Protokolliert die Komprimierung/Token-Metriken der Aktionsantworten als JSONL

• LOGGING_LEVEL (optional): debug | info | warn | error

Schnelle Überprüfung nach dem Start

Überprüfen Sie nach der Verbindung zuerst diese 3 Punkte. Selbst wenn sich Dokumente nicht öffnen lassen, können Sie so schnell eingrenzen, wo der Fehler liegt.

1. Vault-Status prüfen

"Vault 상태를 요약해줘."

Erwartetes internes Verhalten:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": { "action": "stats" }
  }
}

Bei normalem Betrieb enthält die Antwort totalFiles, isInitialized und vaultPath.

2. Suchindex prüfen

"노트 제목에 'MCP'가 들어간 문서만 5개 찾아줘."

Erwartetes internes Verhalten:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "search",
      "keyword": "MCP",
      "limit": 5
    }
  }
}

Wenn das Ergebnis bei search leer ist, prüfen Sie die Indizierung, den Pfad oder den Suchbereich.

3. Dokumentenlesung prüfen

"특정 노트 하나를 읽어줘."

Erwartetes internes Verhalten:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "read",
      "filename": "예: 어떤 문서 이름"
    }
  }
}

Wenn der filename falsch ist, erhalten Sie { "error": "Document not found: ..." }. Es ist schneller, zuerst list_all zu verwenden, um Kandidaten zu prüfen, anstatt read.

search, list_all und load_memory haben standardmäßig quiet: true, wodurch die Standardantwort kurz ausfallen kann. Verwenden Sie bei Bedarf quiet: false, includeContent: true und excerptLength (oder maxOutputChars), um Details zu erhalten.

Anwendungsbeispiele

Es ist wichtiger, "was Sie tun möchten", als wie Sie das MCP aufrufen.

Beispiel für das Organisieren von Anhängen, die in einem Markdown-Dokument referenziert sind:

https://github.com/user-attachments/assets/eb74ec05-09f7-4632-a22c-666b7e844147

• Wenn Sie verlangen, dass die in einem bestimmten Dokument referenzierten Bildanhänge organisiert werden, erstellt das Tool einen Ordner mit dem Namen der Datei innerhalb des images-Ordners und verschiebt die Dateien dorthin.

• Das organisierte Dokument wird aktualisiert, um die Verbindungen basierend auf dem neuen images-Ordner beizubehalten, damit die Verknüpfungen nicht unterbrochen werden.

Beispiele für direkte Anfragen:

• "Suche im README.md nur den Teil Erste Schritte (Schnelleinrichtung) unter MCP-Client-Konfiguration."

• "Lies und fasse nur das vault-Konfigurationsbeispiel in docs/tools-usage-guide.md zusammen."

• "Suche in docs/tool-reference.md nur nach dem collect_context-Parameter von vault."

• "Fasse nur den MCP-Server-Konfigurationsblock in docs/tools-usage-guide.md zusammen."

Natürliche Sprachbeispiele funktionieren präziser, wenn sie spezifisch formuliert sind:

• "Suche im Abschnitt 'Erste Schritte' der README.md nur nach Beispielen für Ausführungsbefehle."

• "Suche und vergleiche nur die vault-bezogenen Anwendungsbeispiele in docs/tools-usage-guide.md."

• "Lies nur die Beschreibung des vault.read-Parameters in docs/tool-reference.md."

vault wird intern basierend auf der Benutzerfrage zugeordnet und aufgerufen. Der tatsächliche Ablauf sieht wie folgt aus:

• "Zeige mir nur das npx-Beispiel aus 'Erste Schritte (Schnelleinrichtung)' in der README.md" → Die Schlüsselwörter werden extrahiert und vault.search wird zuerst aufgerufen.

• "Lies nur den collect_context-Parameter aus docs/tool-reference.md" → Zuerst wird der entsprechende Teil des Dokuments mit vault.read gelesen und bei Bedarf mit vault.collect_context zusammengefasst.

• "Lies den Frontmatter-Verarbeitungsprozess aus docs/tools-usage-guide.md" → Der Dokumentenstandort wird mit vault.read gefunden, danach werden generate_property/write_property/create_document_with_properties nacheinander aufgerufen.

Die Aufruf-Flows der Werkzeuge finden Sie mit konkreten JSON-Beispielen unter Anwendungsbeispiele (Tool-Aufruf-Flows).

Registrierte Werkzeuge

• Obsidian Tools (6 Aktionen)

  • vault

    • search

    • read

    • list_all

    • stats

    • collect_context

    • load_memory

• generate_property

• write_property

• create_document_with_properties

• organize_attachments

Detaillierte Nutzungsbedingungen

• Detaillierte Funktionsweisen der Werkzeuge, Standardwerte für Parameter und tatsächliche Antwortformate finden Sie in der Tool-Referenz.

• vault ist ein einzelnes MCP-Tool, bei dem die tatsächliche Aktion über den action-Wert verzweigt wird. Tippfehler sind die häufigste Fehlerursache.

• Beginnen Sie bei großen Vaults mit collect_context bei scope="all" und einem kleinen maxDocs-Wert und erweitern Sie diesen schrittweise.