Obsidian MCP Server

obsidian-mcp-server is an MCP server that allows AI agents to browse, search, and summarize Markdown documents in an Obsidian Vault.

Beyond simply reading documents, this project provides local hybrid search using transformers.js and includes an interactive CLI AI Agent UI that allows you to chat with your Vault directly from the terminal.

Key Features

• 🔍 Hybrid Search: Combines keyword search with semantic (vector) search, providing optimal results through RRF (Reciprocal Rank Fusion) and Reranking.

• 🚀 Zero-Dependency Local AI: Uses @huggingface/transformers to run embedding and reranking models directly within the Node.js process (no external API server required).

• 💬 Built-in CLI Agent: Provides a terminal-based UI that uses MCP tools to ask questions about Vault content and receive answers. View Details

• 📦 Token Optimization: Offers various compression modes and output limits to control the AI agent's token usage.

Related MCP server: Obsidian MCP

What You Can Do (MCP Tools)

• Integrated Search (vault, action="search"): Performs keyword and semantic-based searches simultaneously to find highly relevant documents.

• Read Document (vault, action="read"): Retrieves the content and metadata of a specific note.

• List and Stats (vault, action="list_all"|"stats"): Checks the overall status and file list of the Vault.

• Collect Context (vault, action="collect_context"): Generates high-density knowledge packets related to a specific topic.

• Load Knowledge (vault, action="load_memory"): Recalls saved memory snapshots.

• Frontmatter Management (generate_property|write_property): Generates and applies AI-based metadata.

• Organize Attachments (organize_attachments): Automatically moves images within documents to a dedicated folder and updates links.

Installation and Setup

1. Prerequisites

• Node.js: v22.0.0 or higher

• Obsidian Vault: You must know the absolute path.

2. Install Local AI Models (Required)

To enable semantic search and reranking features, you must download the necessary local models using the command below:

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

Or, if you have already installed the package:

obsidian-mcp-server setup

This command downloads the Xenova/paraphrase-multilingual-MiniLM-L12-v2 (embedding) and Xenova/bge-reranker-base (reranking) models and saves them to the local cache.

3. Environment Variable Setup

MCP Client Configuration Example

In each client configuration, modify env.VAULT_DIR_PATH to your own Vault path.

Claude Desktop / Cursor / Copilot

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

How Hybrid Search Works

To capture semantic relationships that are difficult to find with traditional keyword search alone, it goes through the following pipeline:

1. Keyword Search: Extracts exact word matching results via the internal Indexer.

2. Vector Search: Searches for semantically similar chunks using LanceDB and transformers.js embeddings.

3. RRF Fusion: Merges the rankings of both search results using the Reciprocal Rank Fusion algorithm.

4. Local Reranking: Re-evaluates the merged top results with the BGE Reranker model to determine the final ranking.

If the models are not installed, it automatically operates in keyword-only mode and displays a message in the terminal recommending the execution of npx @sunub/obsidian-mcp-server setup.

Interactive CLI AI Agent UI

This project includes a terminal-based AI chat interface optimized for Obsidian Vault.

Features

• RAG Integration: Automatically collects relevant context from the Vault when asked a question and passes it to the LLM.

• Real-time Streaming: Renders the LLM's response and "thought process ()" in real-time.

• Slash Commands: MCP tools such as /search, /read, and /index can be called directly as commands from the CLI.

• Multi-MCP Management: Monitors the status and tool list of all connected MCP servers.

How to Run

1. Run Chat Model Server: Start a server like llama.cpp or Ollama in OpenAI-compatible mode.

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

2. Run CLI:

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

Slash Command Help

• /search <keyword>: Execute hybrid search

• /read "filename": Read a specific document

• /stats: Check Vault status

• /index: Force re-indexing of the vector DB

• /tools: View a list of all available MCP tools

• /help: View help

License

Apache-2.0