Power your agent
Lệnh của chính nhà phát hành. Không phải endpoint của PlugMCP.
Host a copy with our keys and logs.
npx -y @dalecb/[email protected]Claude Code không có liên kết cài đặt cho lệnh cục bộ. Sao chép lệnh bên dưới và chạy trong terminal.
OBSIDIAN_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.1Chạy trong terminal.
{ "mcpServers": { "io.github.dalecb-obsidian-semantic-mcp": { "command": "npx", "args": [ "-y", "@dalecb/[email protected]" ], "env": { "OBSIDIAN_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_desktop_config.json
URL từ xa hay một lệnh trên máy của bạn? Hai cách cài đặt khác nhau thế nào
Chạy trên PlugMCP
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.
MởTừ nhà phát hành
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
Read-only semantic search MCP server for Obsidian vaults using local Ollama embeddings.
No note writes. No cloud embeddings by default. No Obsidian plugin runtime. No sync service.
Status:
0.3.1early preview. The server is usable today, but ranking behavior and tool schemas may change before1.0.
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"
}
]
}
Requirements:
>= 24Install 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
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 }
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.
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.
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):
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:
Do not use this if you want an Obsidian UI plugin, automatic note generation, or write-capable vault automation.
index_statusReturns index metadata and safety settings.
index_vaultBuilds or updates the external SQLite index.
{ "mode": "incremental" }
Specific files:
{
"mode": "incremental",
"paths": ["02_Projects/My Note.md"]
}
search_notesSearches notes with hybrid semantic and keyword ranking.
{
"query": "live coding notes",
"limit": 8,
"mode": "hybrid"
}
Modes:
hybrid: semantic vector + SQLite FTS5 + metadata boostssemantic: vector-first searchkeyword: FTS5 keyword search without embedding the queryread_noteReads a note or line range by vault-relative path.
{
"path": "02_Projects/My Note.md",
"start_line": 10,
"end_line": 40
}
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.
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-*/.)node_modules, cache, logs2. 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?
OBSIDIAN_SEMANTIC_EXCLUDEOBSIDIAN_SEMANTIC_SENSITIVE_PATHS + OBSIDIAN_SEMANTIC_ALLOW_SENSITIVEAdditional guards:
realpath.
search_notesandread_noteenforce 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 withindex_status.
The local index stores snippets and embedding vectors. Treat it as a derived copy of your vault. See PRIVACY.md.
The default is action-driven, not timer-based:
search_notes after server start.search_notes after a Markdown create, update, delete, or rename event.search_notes after the embedding model or index format changes; this triggers a full rebuild.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.
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.
npm test
npm run pack:check
Before publishing:
npm pack --dry-run
Confirm the package does not include data/, *.sqlite, or private vault files.
MIT
Read-only semantic search MCP server for Obsidian vaults using local Ollama embeddings.
{ "mcpServers": { "io.github.dalecb-obsidian-semantic-mcp": { "command": "npx", "args": [ "-y", "@dalecb/[email protected]" ], "env": { "OBSIDIAN_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>" } } }}Công cụ
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Nhà phát hành liệt kê các biến môi trường sau: 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.
Obsidian Semantic Search chạy cục bộ qua stdio.
Kiểm tra lần cuối: 2026-11-09. Read-only semantic search MCP server for Obsidian vaults using local Ollama embeddings.