Sunub Obsidian MCP Server

What sunub-obsidian-mcp-server does

sunub-obsidian-mcp-server MCP server exposes an Obsidian Vault’s Markdown documents to MCP-compatible AI clients. It supports both read and write workflows: agents can find notes, inspect their contents and metadata, assemble related evidence into a memory_packet, generate frontmatter candidates, update properties, create documents with properties, and reorganize attachments while updating links.

The server is designed for local-first Vault access. Its retrieval pipeline is intended to provide selected excerpts and source references rather than sending entire documents into an agent context by default. This makes it suitable for questions that require evidence from a personal knowledge base, topic-based context gathering, or structured maintenance of Obsidian notes.

How it works

The default retrieval path combines several stages. An internal index first finds keyword matches, while LanceDB and a local embedding model identify semantically similar chunks. Reciprocal rank fusion combines those result sets, and a local reranker evaluates the leading candidates again. The server then returns excerpts, evidence snippets, source references, or a memory_packet suited to the requested operation.

sunub-obsidian-mcp-server MCP server falls back to keyword search if the local embedding or reranking models are unavailable. Running the setup command installs the cached models needed for semantic retrieval and reranking. The collect_context tool is intended for selecting related documents and compressing a topic into context; search and read are simpler choices for individual lookups.

Setup and configuration

The runtime requires Node.js 22 or newer and an accessible absolute path to an Obsidian Vault. Run npx @sunub/obsidian-mcp-server setup to prepare the local semantic-search and reranking models. The package can then be registered with an MCP client using npx -y @sunub/obsidian-mcp-server@latest and the required VAULT_DIR_PATH environment variable.

VAULT_DIR_PATH must point to the Vault’s absolute filesystem path. LOGGING_LEVEL is optional and accepts debug, info, warn, or error. LLM_API_URL and LLM_CHAT_MODEL apply to the repository’s development CLI interface, not to the core Vault MCP tools.

Tools and capabilities

The available operations include:

• search: combines keyword and semantic retrieval to find candidate notes.
• read: returns a selected note’s body and metadata.
• list_all: lists documents in the Vault.
• stats: reports Vault and index status.
• collect_context: selects related documents and creates a memory_packet.
• load_memory: loads a saved context-memory snapshot.
• generate_property: proposes frontmatter properties from document content.
• write_property: writes frontmatter properties.
• create_document_with_properties: analyzes a document, then generates and writes its properties.
• organize_attachments: organizes document attachments and updates links.

Limitations and notes

sunub-obsidian-mcp-server MCP server depends on a valid Vault path; a missing or incorrect VAULT_DIR_PATH prevents Vault tools from working. Semantic search and reranking are unavailable at their intended quality until the setup command installs the local models, although keyword search can still operate.

The repository also contains a development-only terminal CLI, but the published package entry point starts the MCP server rather than that interface. The CLI requires a separate OpenAI-compatible local LLM endpoint and uses LLM_API_URL and LLM_CHAT_MODEL. Its conditional RAG behavior gathers Vault context only when Vault-related commands, server names, or tool names trigger that path. Write tools are restricted from writing outside the Vault.