Obsidian MCP-Server

👁 npm version

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

Dieses Projekt geht über das bloße Lesen von Dokumenten hinaus: Es bietet eine lokale hybride Suche mittels transformers.js und enthält eine interaktive CLI-KI-Agenten-Benutzeroberfläche, mit der Sie direkt im Terminal mit Ihrem Vault kommunizieren können.

Hauptmerkmale

• 🔍 Hybride Suche: Kombiniert Stichwortsuche mit semantischer (Vektor-)Suche und liefert optimale Ergebnisse durch RRF (Reciprocal Rank Fusion) und Reranking.

• 🚀 Zero-Dependency lokale KI: Nutzt @huggingface/transformers, um Embedding- und Reranking-Modelle direkt im Node.js-Prozess auszuführen (kein externer API-Server erforderlich).

• 💬 Integrierter CLI-Agent: Bietet eine terminalbasierte Benutzeroberfläche, um Fragen zum Vault-Inhalt zu stellen und Antworten mithilfe von MCP-Tools zu erhalten. Mehr dazu

• 📦 Token-Optimierung: Bietet verschiedene Komprimierungsmodi und Ausgabebeschränkungen, um den Token-Verbrauch von KI-Agenten zu steuern.

Was ist möglich (MCP-Tools)

• Integrierte Suche (vault, action="search"): Führt gleichzeitig Stichwort- und semantische Suchen durch, um relevante Dokumente zu finden.

• Dokumentenansicht (vault, action="read"): Abruf von Inhalt und Metadaten einer bestimmten Notiz.

• Gesamtliste und Status (vault, action="list_all"|"stats"): Überprüfung des allgemeinen Vault-Status und der Dateiliste.

• Kontextsammlung (vault, action="collect_context"): Erstellung hochdichter Wissenspakete zu einem bestimmten Thema.

• Wissensabruf (vault, action="load_memory"): Aufruf gespeicherter Speicher-Snapshots.

• Frontmatter-Verwaltung (generate_property|write_property): KI-basierte Generierung und Anwendung von Metadaten.

• Organisation von Anhängen (organize_attachments): Automatisches Verschieben von Bildern innerhalb von Dokumenten in einen dedizierten Ordner und Aktualisierung der Links.

Installation und Einrichtung

1. Voraussetzungen

• Node.js: v22.0.0 oder höher

• Obsidian Vault: Der absolute Pfad muss bekannt sein.

2. Installation lokaler KI-Modelle (erforderlich)

Um die semantische Suche und Reranking-Funktionen zu aktivieren, müssen die erforderlichen lokalen Modelle über den folgenden Befehl heruntergeladen werden:

# 로컬 임베딩 및 리랭킹 모델 설치
npx @sunub/obsidian-mcp-server setup

Oder, falls das Paket bereits installiert ist:

obsidian-mcp-server setup

Dieser Befehl lädt die Modelle Xenova/paraphrase-multilingual-MiniLM-L12-v2 (Embedding) und Xenova/bge-reranker-base (Reranking) herunter und speichert sie im lokalen Cache.

3. Umgebungsvariablen konfigurieren

Beispiel für die MCP-Client-Konfiguration

Passen Sie in der jeweiligen Client-Konfiguration env.VAULT_DIR_PATH an Ihren eigenen Vault-Pfad an.

Claude Desktop / Cursor / Copilot

{
 "mcpServers": {
 "obsidian": {
 "command": "npx",
 "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
 "env": {
 "VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
 }
 }
 }
}

Funktionsweise der hybriden Suche

Um semantische Zusammenhänge zu erfassen, die mit herkömmlicher Stichwortsuche schwer zu finden sind, wird folgende Pipeline durchlaufen:

1. Stichwortsuche: Extraktion exakter Wortübereinstimmungen über den internen Indexer.

2. Vektorsuche: Suche nach semantisch ähnlichen Chunks mittels LanceDB und transformers.js-Embeddings.

3. RRF Fusion: Zusammenführung der Rangfolgen beider Suchergebnisse mittels des Reciprocal Rank Fusion-Algorithmus.

4. Lokales Reranking: Neubewertung der zusammengeführten Top-Ergebnisse durch das BGE Reranker-Modell zur Bestimmung der endgültigen Rangfolge.

Wenn keine Modelle installiert sind, arbeitet das System automatisch im reinen Stichwort-Modus und zeigt im Terminal eine Empfehlung zur Ausführung von npx @sunub/obsidian-mcp-server setup an.

Interaktive CLI-KI-Agenten-UI

Dieses Projekt enthält eine terminalbasierte KI-Chat-Schnittstelle, die für Obsidian-Vaults optimiert ist.

Merkmale

• RAG-Integration: Bei Fragen wird automatisch relevanter Kontext aus dem Vault gesammelt und an das LLM übermittelt.

• Echtzeit-Streaming: Rendert die Antworten des LLMs und den "Denkprozess ()" in Echtzeit.

• Slash-Befehle: MCP-Tools wie /search, /read oder /index können direkt als Befehle in der CLI aufgerufen werden.

• Multi-MCP-Verwaltung: Überwacht den Status und die Tool-Liste aller verbundenen MCP-Server.

Ausführung

1. Chat-Modell-Server starten: Starten Sie einen Server wie llama.cpp oder Ollama im OpenAI-kompatiblen Modus.

   • Beispiel: llama-server -m models/gemma-2-9b-it.Q4_K_M.gguf --port 8080

2. CLI ausführen:

   # 환경변수와 함께 실행
   VAULT_DIR_PATH="/your/vault" LLM_API_URL="http://localhost:8080" npx @sunub/obsidian-mcp-server

Hilfe zu Slash-Befehlen

• /search <keyword>: Führt eine hybride Suche aus

• /read "filename": Liest ein bestimmtes Dokument

• /stats: Überprüft den Vault-Status

• /index: Erzwingt eine Neuindizierung der Vektor-DB

• /tools: Zeigt eine Liste aller verfügbaren MCP-Tools an

• /help: Zeigt die Hilfe an

Lizenz

Apache-2.0

Maintenance

Resources

• Remote Server
• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• create_document_with_propertiesA
• generate_propertyA
• organize_attachmentsA
• vaultA
• write_propertyA