obsidian-mcp-server

Implements dual-transport MCP server architecture (stdio for local CLI/IDE integration, HTTP for remote agents) that translates MCP protocol messages into Obsidian Local REST API calls. Uses @modelcontextprotocol/sdk with a layered transport abstraction pattern, maintaining separate Server instances per transport mode while sharing a unified service layer for vault operations. Stdio transport creates persistent process-based communication for tools like Claude Desktop; HTTP transport exposes the same MCP tools over REST with configurable CORS and authentication.

Implements obsidian_read_note tool that retrieves file content and YAML frontmatter metadata via the Obsidian REST API's /vault/read endpoint, with automatic parsing of frontmatter using YAML deserialization. Supports reading by file path with optional directory filtering and returns structured output containing raw content, parsed frontmatter object, and file metadata (creation/modification timestamps). Uses schema validation to ensure path safety and prevent directory traversal attacks.

Implements multi-layer input validation using JSON Schema validation for all MCP tool parameters, regex pattern analysis to detect ReDoS vulnerabilities, and path traversal prevention via path normalization and allowlist checking. Validates file paths against vault root to prevent directory traversal attacks, sanitizes regex patterns before passing to Obsidian's search engine, and enforces content size limits. Uses zod or similar schema validation library with custom validators for domain-specific constraints.

Implements VaultCacheService that maintains an in-memory cache of frequently accessed vault metadata (file listings, search results, frontmatter) with configurable TTL-based invalidation. Supports manual cache invalidation on write operations (note updates, deletions) to maintain consistency. Uses LRU eviction policy to prevent unbounded memory growth. Cache keys are based on operation parameters (path, search query, etc.) enabling fine-grained invalidation.

Implements tool registration system where each MCP tool (obsidian_read_note, obsidian_update_note, etc.) is defined as a separate module with standardized interface: name, description, input schema, and handler function. Tools are registered with the MCP server via a registry pattern, enabling dynamic tool discovery and addition of custom tools without modifying core server code. Each tool module exports its schema and handler independently, allowing tools to be tested, versioned, and deployed separately.

Implements obsidian_global_search tool that executes vault-wide content searches via Obsidian REST API's /search/simple endpoint, supporting both plain-text and regex pattern matching with optional result filtering by file type, path prefix, or tag. Returns ranked search results with file paths, matching line snippets, and match positions. Uses schema validation to sanitize regex patterns and prevent ReDoS attacks, with configurable result limits to prevent memory exhaustion.

Implements obsidian_update_note tool that modifies note content via Obsidian REST API's /vault/modify endpoint with three distinct modes: append (add content to end), prepend (add content to start), or overwrite (replace entire content). Preserves YAML frontmatter during updates and supports atomic multi-line insertions. Uses schema validation to prevent path traversal and enforces content size limits to prevent vault corruption.

Implements obsidian_search_replace tool that performs targeted text and regex replacements within a single note via Obsidian REST API's /vault/modify endpoint with search pattern validation. Supports both literal string and regex pattern matching with optional case-insensitive and global flags. Validates regex patterns before execution to prevent ReDoS attacks, and returns match count and preview of changes before applying. Uses atomic updates to ensure consistency.

Implements obsidian_manage_frontmatter tool that performs create, read, update, and delete operations on YAML frontmatter fields via Obsidian REST API. Parses existing frontmatter, applies field-level modifications (add, update, delete, or replace entire frontmatter), and re-serializes to YAML with proper formatting. Uses schema validation to ensure valid YAML structure and prevents injection attacks. Supports nested field access via dot notation (e.g., 'metadata.author').

Implements obsidian_manage_tags tool that adds, removes, and lists tags in both YAML frontmatter ('tags' field) and inline Obsidian syntax (#tag). Automatically detects tag location (frontmatter vs inline) and applies modifications to the appropriate location. Supports bulk tag operations and tag normalization (lowercase, slug format). Uses schema validation to ensure valid tag format and prevents duplicate tags.

Implements obsidian_list_notes tool that enumerates vault files via Obsidian REST API's /vault/list endpoint with support for recursive directory traversal, file type filtering (markdown, images, etc.), and path prefix filtering. Returns structured file metadata including paths, file types, creation/modification timestamps, and optional file sizes. Uses schema validation to prevent directory traversal attacks and supports pagination for large directories.

Implements obsidian_delete_note tool that removes files from the vault via Obsidian REST API's /vault/delete endpoint with optional safety checks (confirmation flag, path validation). Supports deletion of individual files or entire directories with recursive flag. Uses schema validation to prevent accidental deletion of critical files and enforces path safety to prevent directory traversal attacks.

Implements request context tracking via RequestContext class that assigns unique IDs to each MCP tool invocation and propagates context through the entire call stack (transport layer → services → Obsidian REST API calls). Integrates structured logging with context injection, enabling correlation of logs across multiple service calls. Uses async-local-storage pattern to maintain context without explicit parameter passing. Logs all Obsidian REST API calls with request/response details and error information.