Obsidian Vault

Obsidian MCP Server

Empower your AI agents and development tools with seamless Obsidian integration!

An MCP (Model Context Protocol) server providing comprehensive access to your Obsidian vault. Enables LLMs and AI agents to read, write, search, and manage your notes and files through the Obsidian Local REST API plugin.

Built on the cyanheads/mcp-ts-template, this server follows a modular architecture with robust error handling, logging, and security features.

🚀 Core Capabilities: Obsidian Tools 🛠️

This server equips your AI with specialized tools to interact with your Obsidian vault:

Tool Name	Description	Key Features
obsidian_read_note	Retrieves the content and metadata of a specified note.	- Read in markdown or json format. - Case-insensitive path fallback. - Includes file stats (creation/modification time).
obsidian_update_note	Modifies notes using whole-file operations.	- append, prepend, or overwrite content. - Can create files if they don't exist. - Targets files by path, active note, or periodic note.
obsidian_search_replace	Performs search-and-replace operations within a target note.	- Supports string or regex search. - Options for case sensitivity, whole word, and replacing all occurrences.
obsidian_global_search	Performs a search across the entire vault.	- Text or regex search. - Filter by path and modification date. - Paginated results.
obsidian_list_notes	Lists notes and subdirectories within a specified vault folder.	- Filter by file extension or name regex. - Provides a formatted tree view of the directory.
obsidian_manage_frontmatter	Atomically manages a note's YAML frontmatter.	- get, set, or delete frontmatter keys. - Avoids rewriting the entire file for metadata changes.
obsidian_manage_tags	Adds, removes, or lists tags for a note.	- Manages tags in both YAML frontmatter and inline content.
obsidian_delete_note	Permanently deletes a specified note from the vault.	- Case-insensitive path fallback for safety.

---

Table of Contents

| Overview | Features | Configuration | | Project Structure | Vault Cache Service | | Tools | Resources | Development | License |

Overview

The Obsidian MCP Server acts as a bridge, allowing applications (MCP Clients) that understand the Model Context Protocol (MCP) – like advanced AI assistants (LLMs), IDE extensions, or custom scripts – to interact directly and safely with your Obsidian vault.

Instead of complex scripting or manual interaction, your tools can leverage this server to:

• Automate vault management: Read notes, update content, manage frontmatter and tags, search across files, list directories, and delete files programmatically.
• Integrate Obsidian into AI workflows: Enable LLMs to access and modify your knowledge base as part of their research, writing, or coding tasks.
• Build custom Obsidian tools: Create external applications that interact with your vault data in novel ways.

Built on the robust mcp-ts-template, this server provides a standardized, secure, and efficient way to expose Obsidian functionality via the MCP standard. It achieves this by communicating with the powerful Obsidian Local REST API plugin running inside your vault.

Developer Note: This repository includes a .clinerules file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.

Features

Core Utilities

Leverages the robust utilities provided by cyanheads/mcp-ts-template:

• Logging: Structured, configurable logging (file rotation, console, MCP notifications) with sensitive data redaction.
• Error Handling: Centralized error processing, standardized error types (McpError), and automatic logging.
• Configuration: Environment variable loading (dotenv) with comprehensive validation.
• Input Validation/Sanitization: Uses zod for schema validation and custom sanitization logic.
• Request Context: Tracking and correlation of operations via unique request IDs.
• Type Safety: Strong typing enforced by TypeScript and Zod schemas.
• HTTP Transport Option: Built-in Hono server with SSE, session management, CORS support, and pluggable authentication strategies (JWT and OAuth 2.1).

Obsidian Integration

• Obsidian Local REST API Integration: Communicates directly with the Obsidian Local REST API plugin via HTTP requests managed by the ObsidianRestApiService.
• Comprehensive Command Coverage: Exposes key vault operations as MCP tools (see Tools section).
• Vault Interaction: Supports reading, updating (append, prepend, overwrite), searching (global text/regex, search/replace), listing, deleting, and managing frontmatter and tags.
• Targeting Flexibility: Tools can target files by path, the currently active file in Obsidian, or periodic notes (daily, weekly, etc.).
• Vault Cache Service: An intelligent in-memory cache that improves performance and resilience. It caches vault content, provides a fallback for the global search tool if the live API fails, and periodically refreshes to stay in sync.
• Safety Features: Case-insensitive path fallbacks for file operations, clear distinction between modification types (append, overwrite, etc.).

Installation

Prerequisites

1. Obsidian: You need Obsidian installed.
2. Obsidian Local REST API Plugin: Install and enable the Obsidian Local REST API plugin within your Obsidian vault.
3. API Key: Configure an API key within the Local REST API plugin settings in Obsidian. You will need this key to configure the server.
4. Node.js & npm: Ensure you have Node.js (v18 or later recommended) and npm installed.

Configuration

MCP Client Settings

Add the following to your MCP client's configuration file (e.g., cline_mcp_settings.json). This configuration uses npx to run the server, which will automatically download & install the package if not already present:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": ["obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: Verify SSL is set to false here because the Obsidian Local REST API plugin uses a self-signed certificate by default. If you are deploying this in a production environment, consider using the encrypted HTTPS endpoint and set OBSIDIAN_VERIFY_SSL to true after configuring your server to trust the self-signed certificate.

If you installed from source, change command and args to point to your local build:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_OBSIDIAN_API_KEY",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      

---

*README truncated. [View full README on GitHub](https://github.com/cyanheads/obsidian-mcp-server).*