Obsidian Semantic Search MCP server

Obsidian Semantic Search MCP

Read-only semantic retrieval for agents that need to find the right Obsidian note without write access.

한국어 · Quick Start · Why This Exists · How It Works

Your Obsidian vault is useful only if your agent can find the right note.

Keyword search misses context. Full write-capable Obsidian MCP servers expose more power than a retrieval agent needs. Obsidian plugins are great inside Obsidian, but they are not always the right boundary for Codex, Claude Desktop, Cursor, or any other MCP client.

This project is the narrow version:

local Obsidian vault -> read-only scanner -> local SQLite index -> MCP search/read tools

No note writes. No cloud embeddings by default. No Obsidian plugin runtime. No sync service.

Status: 0.3.1 early preview. The server is usable today, but ranking behavior and tool schemas may change before 1.0.

What You Get

Example result shape:

{
  "path": "02_Projects/RealtimeAPI/05_Interview_QA.md",
  "title": "Interview Q&A",
  "score": 0.7431,
  "matched_sections": [
    {
      "heading": "Level 4 > Redis Lua atomicity",
      "lines": [266, 305],
      "reason": "semantic=1, keyword=0.5565, metadata=0.6"
    }
  ]
}

Quick Start

Requirements:

• Node.js >= 24
• Ollama
• An Obsidian vault
• An MCP client such as Codex, Claude Desktop, Cursor, or another stdio MCP client

Install the embedding model:

ollama pull bge-m3
curl http://localhost:11434/api/tags

Print setup guidance:

npx -y --package @dalecb/obsidian-semantic-mcp obsidian-semantic-mcp-setup

Codex Setup

Add this to ~/.codex/config.toml:

[mcp_servers.obsidian_semantic]
command = "npx"
args = ["-y", "@dalecb/obsidian-semantic-mcp"]

[mcp_servers.obsidian_semantic.env]
OBSIDIAN_VAULT_ROOT = "/path/to/your/Obsidian Vault"
OBSIDIAN_SEMANTIC_MCP_HOME = "/Users/you/.obsidian-semantic-mcp"
OLLAMA_BASE_URL = "http://localhost:11434"
OBSIDIAN_EMBED_MODEL = "bge-m3"
OBSIDIAN_SEMANTIC_AUTO_INDEX = "true"

Restart Codex, then run:

obsidian_semantic.index_status
obsidian_semantic.search_notes { "query": "Redis Lua atomicity", "limit": 5 }

Claude Code Setup

Add the server at user scope so the personal vault path stays out of project .mcp.json files:

Shortened. The full README is on GitHub.