Skip to main content
Glama
obsidian-knowledge-mcp

obsidian-knowledge-mcp

by HY2MHY

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

obsidian_search_notes

Find relevant note sections with filters and pagination

obsidian_read_note

Read one note or an exact heading as evidence

obsidian_list_notes

Browse by folder prefix or tag

obsidian_find_backlinks

Follow Obsidian [[wikilinks]] back to related notes

obsidian_vault_stats

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-mcp

The process uses stdio and waits for an MCP client. For an interactive inspection UI:

uv run mcp dev src/obsidian_knowledge_mcp/server.py

Run the included sample vault (English demo · 中文演示):

export OBSIDIAN_VAULT_PATH="$PWD/examples/sample_vault"
uv run mcp dev src/obsidian_knowledge_mcp/server.py

Client 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_PATH is scanned.

  • .obsidian, .git, .trash, node_modules, and attachments are 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, failures

License

MIT. See LICENSE.

Available Tools

5 tools
obsidian_list_notesList Obsidian notesA
Read-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 noteA
Read-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 notesA
Read-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 vaultA
Read-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

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides AI agents with comprehensive access to Obsidian vaults, enabling reading, writing, searching, tagging, linking, canvas manipulation, and semantic search through 41 tools.
      -