Model Context Protocol server for Obsidian vault integration, enabling AI assistants to read, search, and write notes in Obsidian vaults
Obsidian MCP has well-structured tool definitions with clear naming (verb_noun pattern) and comprehensive descriptions. All 8 tools have input schemas with type definitions and parameter descriptions. However, output schemas are not documented, error handling lacks recovery guidance, and several tools have overly verbose descriptions (obsidian_patch_content exceeds 1024 chars). Parameter descriptions are generally good but some lack constraints (e.g., context_length has no min/max bounds). No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications. Missing idempotency guarantees for write operations.
Append content to the end of a new or existing file in the vault. This adds content to the very end of the file. If you need to add content under a specific heading, use the obsidian_patch_content tool instead.
Retrieve the complete content of multiple files from your vault in a single operation. Returns all file contents concatenated with file path headers and separators.
Advanced search using JSONLogic query syntax for complex filtering across vault files. Supports nested conditions, regex patterns, and multiple criteria.
Retrieve the complete content of a single file from your vault. Use this when you need to read an entire note.
Lists all files and directories within a specific folder in your Obsidian vault. Use this to browse the contents of a particular directory.
obsidian_patch_content description exceeds 1024 chars (1,800+), violating pattern:tool-description baseline. Verbose examples and error documentation should move to separate docs or be condensed.
No output schemas documented for any tool. LLMs cannot plan downstream calls or extract fields without knowing return structure. All tools return JSON text but structure is undocumented.
Write tools (obsidian_append_content, obsidian_patch_content) lack idempotency guarantees and confirmation/dry-run support. Agents cannot safely retry on ambiguous failures without risking duplicate writes.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 58 | 2026-07-28+ | v2 |
Lists all files and directories in the root directory of your Obsidian vault. Use this to discover the top-level structure of your vault.
Insert or modify content at a specific location in an existing note. Use this tool when you need to add or modify content under a specific heading, at a block reference, or in frontmatter fields. PARAMETERS: - filepath: The relative path to the file within the vault (e.g., "📔 Periodic Notes/📔 Daily/2025-03-20.md") - operation: Choose "append" (add after target), "prepend" (add before target), or "replace" (replace target) - target_type: Choose "heading", "block", or "frontmatter" - target: Specify what to target (see detailed instructions below) - content: The content you want to add or replace HEADING TARGETS - IMPORTANT RULES: 1. For heading targets, use the FULL PATH from the top-level heading (H1) to your target heading 2. Separate heading levels with "::" (e.g., "2025-03-20::Notes" or "Project Ideas::Development::Web Apps") 3. Use the EXACT heading text without any hash symbols (#) 4. Example of a typical hierarchy: # Main Title (H1) ## Section (H2) ### Subsection (H3) To target the Subsection, use: "Main Title::Section::Subsection" 5. Common errors: - Skipping a heading level (like going H1→H3 without including H2) - Using only the immediate parent heading without the full path - Using incorrect heading text (case, spacing, or special characters matter) BLOCK REFERENCE TARGETS: - Use the block ID without the "^" symbol (e.g., use "2d9b4a" not "^2d9b4a") FRONTMATTER TARGETS: - Use the exact field name in the YAML frontmatter (e.g., "tags" or "status") COMMON ERRORS: - "invalid-target": Double-check that your heading path is complete, starting from H1 - "content-already-preexists-in-target": The exact content already exists at the target - If you get errors, try getting the file contents first to verify the exact heading text and structure EXAMPLES: Example 1: Add content under a Notes heading in a daily note obsidian_patch_content( filepath: "📔 Periodic Notes/📔 Daily/2025-03-20.md", operation: "append", target_type: "heading", target: "2025-03-20::Notes", content: "Hello from Claude\n\n" ) Example 2: Add content under a nested heading obsidian_patch_content( filepath: "Projects/Development.md", operation: "prepend", target_type: "heading", target: "Development::Web Projects::Current", content: "- New project idea\n" ) Example 3: Update a frontmatter field obsidian_patch_content( filepath: "Projects/ProjectX.md", operation: "replace", target_type: "frontmatter", target: "status", content: "In Progress" )
Simple text search across all files in the vault. Returns matches with surrounding context. Use this tool when you need to find specific text or phrases in your notes. Results include filenames with matches and context around each match.
obsidian_simple_search context_length parameter lacks min/max bounds. Unbounded integers let LLMs pass absurd values (e.g., 1000000) that waste tokens or cause timeouts.
obsidian_complex_search accepts a JSONLogic query object but provides no schema, examples, or constraints. LLMs cannot construct valid queries without external documentation.