Obsidian MCP Server

Implements the Model Context Protocol specification to expose read_notes and search_notes as discoverable tools to MCP clients like Claude Desktop. The server registers tool schemas with the MCP client during initialization, enabling standardized tool discovery and invocation through the MCP protocol's tool_call mechanism. This allows any MCP-compatible client to dynamically discover available capabilities without hardcoding tool knowledge.

Reads markdown file contents from the vault by accepting relative file paths, validating them through a Path Validator component that prevents directory traversal attacks (../ patterns), symlink escapes, and hidden file access. The validator ensures all file operations remain within the configured vault root directory before passing validated paths to the file system layer. This security-first approach allows safe external access to vault contents while maintaining strict boundaries.

Performs all file system operations asynchronously using Node.js async APIs (fs.promises) rather than blocking synchronous calls, preventing the server from hanging when reading large files or slow storage. Each operation includes comprehensive error handling for common failures (file not found, permission denied, encoding errors) with descriptive error messages returned to the client. This async-first approach ensures the server remains responsive even under load or with slow storage backends.

Searches the vault for markdown files matching glob patterns (e.g., '*.md', 'notes/**/project*.md') by accepting a search pattern, validating it through the Path Validator to prevent directory traversal in the pattern itself, then executing filesystem glob operations within the vault boundary. Returns a list of matching file paths relative to vault root. This enables AI assistants to discover relevant notes without requiring exact filenames.

Configures the MCP server to bind to a specific Obsidian vault directory or any markdown-containing directory through environment variables or configuration files. The server reads the vault path at startup, validates it exists and is readable, then uses it as the root boundary for all subsequent file operations. This configuration-driven approach allows a single mcp-obsidian installation to serve different vaults by changing configuration without code changes.

Retrieves markdown file contents exactly as stored, preserving all formatting, frontmatter (YAML/TOML), internal links, and metadata. The read_notes tool returns raw file content without parsing or transformation, allowing AI assistants to see the exact note structure including Obsidian-specific syntax like [[internal links]] and #tags. This preservation enables the AI to understand note relationships and metadata without requiring separate metadata extraction.

Enables understanding of Obsidian's internal link graph by exposing raw markdown content that contains [[wiki-style links]] and backlinks. While mcp-obsidian doesn't explicitly parse the link graph, it provides the raw markdown that contains all link information, allowing AI assistants to extract and reason about note relationships by analyzing the [[note-name]] syntax. Combined with the search capability, this enables graph traversal patterns where the AI can follow links to discover related notes.

Implements the MCP server specification in a way that's compatible with multiple MCP clients including Claude Desktop, VS Code with MCP extension, and custom MCP client implementations. The server exposes tools through standard MCP protocol methods (list_tools, call_tool) without client-specific code paths, allowing the same server instance to serve different clients simultaneously. This client-agnostic approach is enabled by strict adherence to the MCP specification.

Provides installation through the Smithery CLI tool (npx @smithery/cli install mcp-obsidian --client claude) which automatically configures mcp-obsidian for Claude Desktop without manual JSON editing. The Smithery installer handles downloading the server, setting up configuration files, and registering the server with Claude Desktop. This abstraction eliminates the need for users to understand MCP configuration details or manually edit JSON files.

Provides VS Code integration through MCP extension badges and manual configuration options, allowing users to install mcp-obsidian directly from VS Code's MCP extension UI. The integration supports both one-click badge installation (if VS Code extension supports it) and manual JSON configuration in VS Code settings. This enables developers to use Obsidian as a knowledge base within their VS Code environment without leaving the editor.

Enforces strict vault boundaries by validating not just file paths but also symlinks and hidden files. The Path Validator component resolves symlinks to their targets and verifies the target is within the vault boundary, preventing symlink-based escape attacks. It also blocks access to hidden files (starting with .) and hidden directories, preventing accidental exposure of system files or configuration. This multi-layer validation ensures that even sophisticated attacks cannot escape the vault directory.