obsidian-knowledge-mcp
Provides read-only tools for searching, reading, listing, backlink navigation, and stats within a local Obsidian vault.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-knowledge-mcp search my vault for notes about the 2026 automation project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Obsidian Knowledge MCP
A private-by-default MCP server that lets AI clients search, read, and traverse a local Obsidian vault without uploading it to an external index.
Status: public-safe prototype · Role: independent design and implementation · Origin: sanitized reconstruction of a knowledge-retrieval component built during a 2026 summer automation project.
中文说明 · Bilingual docs index · Architecture · Evaluation · Failure analysis
What it demonstrates
Five read-only MCP tools for discovery, evidence reading, graph navigation, and vault health.
Transparent ranking: exact phrase + title/heading boosts + English tokens + Chinese 2-grams.
Source-grounded results with vault-relative paths, headings, excerpts, scores, and pagination.
Local privacy boundary: no cloud index, no API key, hidden folders excluded, path traversal rejected.
MCP Python SDK 2.x, structured output, annotations, in-memory integration tests, and a synthetic demo vault.
Related MCP server: Obsidian MCP Server
Tools
Tool | Workflow role |
| Find relevant note sections with filters and pagination |
| Read one note or an exact heading as evidence |
| Browse by folder prefix or tag |
| Follow Obsidian |
| Inspect vault size, link count, and top tags |
All tools are declared read-only and closed-world. The server never edits the vault.
Quick start
Requirements: Python 3.10+ and uv.
git clone <your-repository-url>
cd obsidian-knowledge-mcp
uv sync --extra dev
export OBSIDIAN_VAULT_PATH="/absolute/path/to/your/Obsidian Vault"
uv run obsidian-knowledge-mcpThe process uses stdio and waits for an MCP client. For an interactive inspection UI:
uv run mcp dev src/obsidian_knowledge_mcp/server.pyRun the included sample vault (English demo · 中文演示):
export OBSIDIAN_VAULT_PATH="$PWD/examples/sample_vault"
uv run mcp dev src/obsidian_knowledge_mcp/server.pyClient configuration
Use an absolute path to the repository and vault:
{
"mcpServers": {
"obsidian-knowledge": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/obsidian-knowledge-mcp",
"run",
"obsidian-knowledge-mcp"
],
"env": {
"OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/Obsidian Vault"
}
}
}
}Test and lint
uv run pytest
uv run ruff check .The tests cover ranking, Chinese retrieval, filters, pagination, section reads, backlink resolution, hidden-folder exclusion, traversal prevention, tool discovery, and structured MCP responses.
Privacy and security
Keep private vaults local; do not commit them to this repository.
Only Markdown under
OBSIDIAN_VAULT_PATHis scanned..obsidian,.git,.trash,node_modules, andattachmentsare excluded by default.Returned paths are vault-relative, not absolute.
The project contains only synthetic sample notes. It does not contain employer data, chat exports, credentials, or production identifiers.
Current limitations
Ranking is lexical, not embedding-based; distant paraphrases may need query reformulation.
Wiki-link resolution does not implement every Obsidian alias or duplicate-title edge case.
The index is rebuilt per tool call in v0.1; a watched incremental cache is a future optimization.
The server trusts the local OS user who launches it. It is not a multi-tenant remote service.
Project map
src/obsidian_knowledge_mcp/ search engine and MCP adapter
tests/ unit and in-memory MCP integration tests
examples/sample_vault/ synthetic, reproducible demo data
eval/ stable evaluation questions
docs/ architecture, case, PRD, evaluation, failuresLicense
MIT. See LICENSE.
Available Tools
5 toolsobsidian_find_backlinksFind Obsidian backlinksARead-only
Find notes that link to a target through Obsidian [[wikilinks]].
Use after reading a note to discover related decisions, meetings, or follow-up pages. Matching supports note names, vault-relative paths, aliases, and heading anchors. It never edits the graph.
Inputs: relative_path (required), limit, offset, response_format. Returns: result
obsidian_list_notesList Obsidian notesARead-only
Browse note titles and paths with optional folder and tag filters.
Use when you know the folder or tag but not the exact note name. Results are sorted by path and
paginated; continue with next_offset when has_more is true.
Inputs: tag, limit, offset, prefix, +1 more. Returns: result
obsidian_read_noteRead an Obsidian noteARead-only
Read one note or one heading after discovering its path.
Paths are resolved inside the configured vault, and traversal outside it is rejected. Use an exact heading to keep long notes concise. Returns content, tags, truncation state, and source path.
Inputs: relative_path (required), heading, max_chars.
obsidian_search_notesSearch Obsidian notesARead-only
Search Markdown notes using deterministic phrase, token, and Chinese 2-gram ranking.
Use this first for topical discovery or paraphrased questions. Results include vault-relative
paths, headings, excerpts, tags, scores, and pagination metadata. The tool is local and
read-only.
If results are broad, add prefix or tag; if has_more is true, request next_offset.
Inputs: query (required), tag, limit, offset, +2 more. Returns: result
obsidian_vault_statsSummarize Obsidian vaultARead-only
Return a compact health snapshot of the configured vault.
The response includes note count, wikilink count, distinct tag count, and top tags. Use it to understand vault size before browsing; do not use it for note content retrieval.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool serves a clearly distinct purpose: reading a specific note, searching content, browsing by folder/tag, finding backlinks, and viewing vault stats. There is no meaningful overlap between tools, and the descriptions reinforce when to use each one.
Tool names follow a consistent snake_case pattern with the common `obsidian_` prefix, using clear action-noun combinations like `read_note`, `search_notes`, and `list_notes`. `vault_stats` is the only name that deviates from the verb-object pattern, but the convention remains predictable overall.
Five tools is a well-scoped set for an Obsidian knowledge retrieval server. Each tool adds a distinct capability without redundancy, and the count is neither too thin nor bloated for the domain.
For a read-only knowledge retrieval surface, the tool set covers discovery, browsing, targeted reading, relationship exploration via backlinks, and vault-level stats. Search and list together handle navigation, while backlinks cover knowledge graph traversal; no obvious retrieval workflow is missing.
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to read, search, and manage Obsidian vault markdown files, including YAML frontmatter, wikilinks, and graph operations through a secure stateless I/O layer.MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to read, write, search, and navigate Obsidian vault notes with support for CRUD operations, full-text search, graph navigation, daily notes, and frontmatter management.3,713 npm-
- -licenseNot gradedqualityNot gradedmaintenanceProvides AI agents with comprehensive access to Obsidian vaults, enabling reading, writing, searching, tagging, linking, canvas manipulation, and semantic search through 41 tools.-
- AlicenseAqualityDmaintenanceProvides read-only access to a local Obsidian vault with zero-trust security, enabling note reading, listing, and text search via Claude.3MIT