Obsidian MCP Server

Implements the Model Context Protocol server specification to expose read_notes and search_notes tools to MCP clients like Claude Desktop. The server initializes with protocol-compliant tool definitions, handles tool discovery requests via MCP's tools/list endpoint, and routes tool execution calls through a standardized request-response cycle. This enables any MCP-compatible client to discover and invoke vault operations without custom integration code.

Provides a search_notes tool that accepts glob patterns (e.g., '*.md', 'projects/*.md') and returns matching file paths from the vault. The implementation validates search patterns against the configured vault root directory using a Path Validator component that prevents directory traversal attacks. Search results are returned as a list of relative paths, enabling clients to subsequently read matched files via the read_notes tool.

All file operations use paths relative to the vault root directory rather than absolute filesystem paths. This abstraction isolates clients from the vault's physical location on disk and enables vault portability — the same relative paths work regardless of where the vault directory is mounted. Paths are normalized and validated to ensure they remain within vault boundaries before filesystem access.

Implements the read_notes tool that accepts one or more file paths relative to the vault root and returns their Markdown contents. The Path Validator component validates each requested path before reading, enforcing vault boundary constraints and blocking directory traversal attempts using '../' or absolute paths. File contents are read from disk and returned as plain text, preserving Markdown formatting for client-side rendering.

Implements a dedicated Path Validator security component that intercepts all file operations (read_notes and search_notes) and enforces vault boundary constraints. The validator checks for directory traversal patterns ('../', absolute paths), validates symlink targets remain within vault, detects hidden files/directories, and ensures all operations stay within the configured vault root. This security layer is applied before any filesystem operation executes, preventing unauthorized access to files outside the vault.

Provides filesystem-level indexing of Markdown files within the vault directory, enabling rapid file discovery without parsing file contents. The system scans the vault directory structure, identifies all .md files, and maintains their relative paths for use by search_notes and read_notes tools. This indexing is performed on-demand during search operations rather than pre-computed, avoiding stale index issues but incurring filesystem traversal cost.

Enables configuration of the MCP server to bind to a specific Obsidian vault directory or any directory containing Markdown files. The server accepts a vault path parameter during initialization, validates it exists and is readable, and uses it as the root for all subsequent file operations. This configuration is typically set via Smithery CLI or VS Code settings JSON, allowing users to point the server at their vault without code changes.

Provides automated installation of the mcp-obsidian server into Claude Desktop via the Smithery CLI tool. The installation process downloads the server package, registers it with Claude Desktop's MCP configuration, and sets up the vault path binding. This is the recommended installation method and abstracts away manual configuration file editing, making the server accessible to non-technical users.

Provides VS Code integration via MCP extension badges and manual configuration through VS Code settings JSON. Users can click installation badges in the repository README or manually add the server configuration to their VS Code MCP settings. This enables VS Code users to access Obsidian vaults through the MCP extension without using Claude Desktop, supporting alternative MCP clients.

Reads Markdown files from disk and returns their raw content without parsing, transformation, or interpretation. The read_notes tool preserves all Markdown syntax, frontmatter, and formatting exactly as stored in the vault. This approach enables clients to handle Markdown rendering and interpretation themselves, supporting diverse use cases from plain text processing to semantic parsing.

The read_notes tool accepts an array of file paths and returns contents of multiple files in a single MCP request, reducing round-trip overhead compared to sequential single-file reads. The implementation validates each path independently, reads all files, and returns results as an array or object mapping paths to contents. This enables efficient context assembly for AI agents that need multiple related notes.