How do I install Obsidian Semantic Search?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Obsidian Semantic Search need an API key?

The publisher lists these environment variables: OBSIDIAN_VAULT_ROOT, OBSIDIAN_SEMANTIC_MCP_HOME, OBSIDIAN_EMBED_MODEL, OLLAMA_BASE_URL, OBSIDIAN_SEMANTIC_STARTUP_INDEX, OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE, OBSIDIAN_SEMANTIC_EXCLUDE, OBSIDIAN_SEMANTIC_SENSITIVE_PATHS.

What transport does Obsidian Semantic Search use?

Obsidian Semantic Search runs locally over stdio.

When was Obsidian Semantic Search last checked?

Last checked 2026-11-09. Read-only semantic search MCP server for Obsidian vaults using local Ollama embeddings.

Obsidian Semantic Search MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @dalecb/[email protected]

Credentials from the publisher

OBSIDIAN_VAULT_ROOT — Absolute path to the local Obsidian vault.
OBSIDIAN_SEMANTIC_MCP_HOME — Directory for the external SQLite index, logs, and cache.
OBSIDIAN_EMBED_MODEL — Ollama embedding model name. Defaults to bge-m3.
OLLAMA_BASE_URL — Ollama API base URL. Defaults to http://localhost:11434.
OBSIDIAN_SEMANTIC_STARTUP_INDEX — Set to true to run incremental indexing when the server starts.
OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE — Set to true to allow include_sensitive tool calls.
OBSIDIAN_SEMANTIC_EXCLUDE — Comma- or newline-separated folders to always exclude from indexing, search, and read.
OBSIDIAN_SEMANTIC_SENSITIVE_PATHS — Comma- or newline-separated folders treated as sensitive (blocked unless unlocked). Defaults to 08_PersonalInfo/.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1OBSIDIAN_VAULT_ROOT=<value> OBSIDIAN_SEMANTIC_MCP_HOME=<value> OBSIDIAN_EMBED_MODEL=<value> OLLAMA_BASE_URL=<value> OBSIDIAN_SEMANTIC_STARTUP_INDEX=<value> OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE=<value> OBSIDIAN_SEMANTIC_EXCLUDE=<value> OBSIDIAN_SEMANTIC_SENSITIVE_PATHS=<value> claude mcp add io.github.dalecb-obsidian-semantic-mcp -- npx -y @dalecb/obsidian-semantic-mcp@0.2.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.dalecb-obsidian-semantic-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@dalecb/[email protected]"8      ],9      "env": {10        "OBSIDIAN_VAULT_ROOT": "<value>",11        "OBSIDIAN_SEMANTIC_MCP_HOME": "<value>",12        "OBSIDIAN_EMBED_MODEL": "<value>",13        "OLLAMA_BASE_URL": "<value>",14        "OBSIDIAN_SEMANTIC_STARTUP_INDEX": "<value>",15        "OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE": "<value>",16        "OBSIDIAN_SEMANTIC_EXCLUDE": "<value>",17        "OBSIDIAN_SEMANTIC_SENSITIVE_PATHS": "<value>"18      }19    }20  }21}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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

Need	What this server does
Find the note an agent should read	Hybrid semantic + keyword search over Markdown notes
Keep the vault safe	Exposes search/read/index/status only; no write, patch, move, rename, or delete tools
Stay local-first	Uses Ollama embeddings and stores the index on your machine
Make results agent-friendly	Returns file-level matches with headings, snippets, and line ranges
Avoid plugin state	Reads the vault directly from the filesystem; Obsidian does not need to be running

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:

claude mcp add obsidian_semantic --scope user \
  --env OBSIDIAN_VAULT_ROOT="/path/to/your/Obsidian Vault" \
  --env OBSIDIAN_SEMANTIC_MCP_HOME="/Users/you/.obsidian-semantic-mcp" \
  --env OLLAMA_BASE_URL="http://localhost:11434" \
  --env OBSIDIAN_EMBED_MODEL="bge-m3" \
  --env OBSIDIAN_SEMANTIC_AUTO_INDEX="true" \
  -- npx -y @dalecb/obsidian-semantic-mcp

claude mcp get obsidian_semantic

Start a new Claude Code session and run /mcp to confirm the server is connected. On native Windows, use -- cmd /c npx -y @dalecb/obsidian-semantic-mcp after the environment flags.

See Anthropic's Claude Code MCP documentation for scope and command details.

Claude Desktop / JSON MCP Client Setup

In Claude Desktop, open Settings → Developer → Edit Config. This opens ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows. Merge the following server into mcpServers:

{
  "mcpServers": {
    "obsidian_semantic": {
      "command": "npx",
      "args": ["-y", "@dalecb/obsidian-semantic-mcp"],
      "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"
      }
    }
  }
}

Fully quit and restart Claude Desktop. Cursor and other JSON-style stdio MCP clients can use the same mcpServers entry. On Windows, if npx is not found, use "command": "cmd" and prepend "/c", "npx" to args.

See the official local MCP server guide for Claude Desktop configuration and logs.

Why This Exists

This isn't aiming to be the most powerful Obsidian automation server. It aims to be the safest retrieval tool you can hand an agent.

Here's how it stacks up against the two tools it usually comes down to — a full-permission Obsidian MCP server (Local REST API based) and GBrain (a broader knowledge-compilation platform):

	This project	Full-permission Obsidian MCP	GBrain
Access model	Read-only: search / read / index	Read + write + edit + delete	Read + write; compiles notes into its own model
Touches your vault	Never	Yes	Yes — restructures content
Obsidian must run	No — reads files directly	Yes — needs the REST API plugin	No
Required local runtime	Node.js + Ollama	Obsidian + plugin	Standalone platform
Embeddings & data	Local Ollama by default; remote URL is configurable	Local API; embeddings vary by setup	Built-in pipeline; optional sync
Storage	One SQLite file you can delete and rebuild	Plugin-managed	Its own store / migration
Best for	A small read-only retrieval boundary for agents	Full vault automation and editing	Building a compiled knowledge base across sources

That trade is on purpose: give up writing, editing, and running inside Obsidian, and you get fewer moving parts and a smaller blast radius in return.

Use this if your agent should answer:

"Which note explains this project decision?"
"Find the file where I wrote about idempotency payload mismatch."
"Show me the career notes related to this interview topic."
"Search my vault, but do not mutate it."

Do not use this if you want an Obsidian UI plugin, automatic note generation, or write-capable vault automation.

Tools

`index_status`

Returns index metadata and safety settings.

`index_vault`

Builds or updates the external SQLite index.

{ "mode": "incremental" }

Specific files:

{
  "mode": "incremental",
  "paths": ["02_Projects/My Note.md"]
}

`search_notes`

Searches notes with hybrid semantic and keyword ranking.

{
  "query": "live coding notes",
  "limit": 8,
  "mode": "hybrid"
}

Modes:

hybrid: semantic vector + SQLite FTS5 + metadata boosts
semantic: vector-first search
keyword: FTS5 keyword search without embedding the query

`read_note`

Reads a note or line range by vault-relative path.

{
  "path": "02_Projects/My Note.md",
  "start_line": 10,
  "end_line": 40
}

How It Works

index_vault
  -> scan Markdown files under OBSIDIAN_VAULT_ROOT
  -> block denied paths and symlink escapes
  -> split notes by Markdown headings
  -> create one summary chunk per file
  -> embed chunks with Ollama bge-m3
  -> store notes, chunks, FTS rows, and vectors in SQLite

search_notes
  -> incrementally index on first search or first search after a Markdown change
  -> embed the query with Ollama
  -> score vector similarity
  -> score SQLite FTS5 keyword matches
  -> apply title/path/heading metadata boosts
  -> regroup chunk matches into file-level results

Default storage:

~/.obsidian-semantic-mcp/
  data/semantic.sqlite

The vault remains the source of truth. The SQLite database is a derived index and can be deleted/rebuilt.

Safety Model

The server reads your vault and never writes to it. Three layers decide what an agent can see.

1. Always denied (system / tooling). Never indexed, no override:

.obsidian/, .smart-env/, .claude/, .codex-*/
any hidden folder (name starts with .)
node_modules, cache, logs

2. Sensitive — denied by default, unlockable. Stays blocked even when a tool call passes include_sensitive: true, unless the server is started with OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE=true. Defaults to 08_PersonalInfo/. Override the list with OBSIDIAN_SEMANTIC_SENSITIVE_PATHS (comma- or newline-separated folders):

OBSIDIAN_SEMANTIC_SENSITIVE_PATHS = "08_PersonalInfo, 09_Finance"

3. Your own excludes — always denied. Folders you never want indexed, searched, or read. No unlock flag:

OBSIDIAN_SEMANTIC_EXCLUDE = "03_Journal, Private, Clients/Acme"

Which one do you want?

"Don't index this at all" → OBSIDIAN_SEMANTIC_EXCLUDE
"Keep it locked, but I can unlock it with a flag when I need to" → OBSIDIAN_SEMANTIC_SENSITIVE_PATHS + OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE

Additional guards:

All paths are resolved through realpath.
Path traversal and URL-encoded traversal are blocked.
Symlinks that escape the vault root or point to a denied in-vault path are blocked.

search_notes and read_note enforce the current exclusion settings on every call. With automatic indexing enabled, the next search also removes excluded stale rows from the index. Confirm the active lists with index_status.

The local index stores snippets and embedding vectors. Treat it as a derived copy of your vault. See PRIVACY.md.

Indexing Strategy

The default is action-driven, not timer-based:

The first search_notes after server start.
The first search_notes after a Markdown create, update, delete, or rename event.
The first search_notes after the embedding model or index format changes; this triggers a full rebuild.
An explicit index_vault call.

The filesystem watcher only marks the index dirty. Indexing runs once, immediately before the next search, and concurrent searches share that work. If recursive watching is unavailable, the server falls back to an incremental scan before every search.

Disable automatic indexing with:

OBSIDIAN_SEMANTIC_AUTO_INDEX = "false"

Then call index_vault { "mode": "incremental" } yourself. The legacy OBSIDIAN_SEMANTIC_STARTUP_INDEX=true remains supported, but is not the default because it does work even when no search follows.

Search Quality Evaluation

Create a JSON file containing queries and expected paths to compare keyword, semantic, and hybrid modes under the same conditions:

[
  { "query": "strong consistency at 1000 TPS", "expected_paths": ["03_Knowledge/QnA/Strong-Consistency-at-1000TPS.md"] }
]

npm run evaluate -- ./queries.json 5

The command reports Recall@K and MRR. Avoid adding ranking complexity or embedding cost unless hybrid search measurably beats the keyword baseline.

Refresh the index with search_notes or index_vault before evaluating.

Development

npm test
npm run pack:check

Before publishing:

npm pack --dry-run

Confirm the package does not include data/, *.sqlite, or private vault files.

License

MIT

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Obsidian Semantic Search?

Does Obsidian Semantic Search need an API key?

What transport does Obsidian Semantic Search use?

When was Obsidian Semantic Search last checked?

Documentation

What You Get

Quick Start

Codex Setup

Claude Code Setup

Claude Desktop / JSON MCP Client Setup

Why This Exists

Tools

index_status

index_vault

search_notes

read_note

How It Works

Safety Model

Indexing Strategy

Search Quality Evaluation

Development

License

`index_status`

`index_vault`

`search_notes`

`read_note`