# Obsidian Mcp Server Enhanced

> This is an enhanced version of the excellent cyanheads/obsidian-mcp-server with additional features specifically tailored for remote Claude.ai integration, advanced task querying, and security via Tailscale.

- **Type:** MCP server
- **Install:** `agentstack add mcp-boweylou-obsidian-mcp-server-enhanced`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BoweyLou](https://agentstack.voostack.com/s/boweylou)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [BoweyLou](https://github.com/BoweyLou)
- **Source:** https://github.com/BoweyLou/obsidian-mcp-server-enhanced

## Install

```sh
agentstack add mcp-boweylou-obsidian-mcp-server-enhanced
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Obsidian MCP Server - Enhanced

[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](./CHANGELOG.md)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/BoweyLou/obsidian-mcp-server-enhanced/issues)
[](https://github.com/cyanheads/obsidian-mcp-server)

**Enhanced Obsidian MCP Server with Claude.ai Remote Integration, Tailscale Support, and Advanced Query Capabilities!**

> **🔥 Enhanced Fork Notice:** This is an enhanced version of the excellent [cyanheads/obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server) with additional features specifically tailored for remote Claude.ai integration, advanced task querying, and security via Tailscale.

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](https://github.com/coddingtonbear/obsidian-local-rest-api).

Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture with robust error handling, logging, and security features.

## 🚀 Enhanced Features (This Fork)

### 🏛️ **Multi-Vault Support**
Simultaneous access to multiple Obsidian vaults through a single MCP server:
- **Multiple Vault Management**: Connect to multiple Obsidian instances on different ports simultaneously
- **Vault-Specific Routing**: Tools automatically route to the correct vault based on `vault` parameter
- **Individual Authentication**: Separate API keys for each vault with centralized MCP authentication
- **Backwards Compatible**: Existing single-vault configurations continue to work unchanged
- **Dynamic Configuration**: JSON-based vault configuration with validation and error handling

### 🌐 **Claude.ai Remote Integration**
Perfect integration with Claude.ai's Remote MCP feature:
- **Stateless HTTP Mode**: Dedicated stateless transport for Claude.ai compatibility (`MCP_HTTP_STATELESS=true`)
- **Session-Based Mode**: Traditional session management for other MCP clients
- **Simplified Authentication**: Uses dedicated MCP_AUTH_KEY for server access
- **Zero Configuration**: Works out-of-the-box with Claude.ai Remote MCP servers
- **Production Ready**: Enterprise-grade stability and error handling

### 🔒 **Tailscale Secure Remote Access**
Access your Obsidian vault securely from anywhere:
- **Tailscale Funnel Integration**: Secure HTTPS endpoints with automatic certificates
- **End-to-End Encryption**: All traffic encrypted through Tailscale network
- **No Port Forwarding**: Zero network configuration required
- **Access Control**: Built-in Tailscale ACL support for enterprise security

### 📊 **Enhanced Task & Query System**
Advanced querying capabilities beyond the original:
- **Tasks Plugin Integration**: Deep integration with Obsidian Tasks plugin
- **Advanced Date Parsing**: Natural language date recognition
- **Priority Detection**: Visual and text-based priority parsing
- **Multiple Output Formats**: Table, list, and summary views

### 🔧 **Production Monitoring & Reliability**
Enterprise-grade monitoring and auto-restart capabilities:
- **Health Check Script**: Comprehensive component validation (`scripts/health-check.sh`)
- **Intelligent Monitoring**: Auto-restart with process lifecycle management (`scripts/monitor-mcp.sh`)
- **macOS Auto-Start**: Launch agent configuration for system startup (`scripts/setup-autostart.sh`)
- **Dynamic Port Management**: Automatic port conflict resolution (3010-3013 range)
- **Enhanced Logging**: Detailed connection debugging and API key validation

## 🚀 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_file`](./src/mcp-server/tools/obsidianReadFileTool/)                   | Retrieves the content and metadata of a specified file.         | - Read in `markdown` or `json` format.- Case-insensitive path fallback.- Includes file stats (creation/modification time).                   |
| [`obsidian_update_file`](./src/mcp-server/tools/obsidianUpdateFileTool/)               | 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`](./src/mcp-server/tools/obsidianSearchReplaceTool/)         | 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`](./src/mcp-server/tools/obsidianGlobalSearchTool/)           | Performs a search across the entire vault.                      | - Text or regex search.- Filter by path and modification date.- Paginated results.                                                           |
| [`obsidian_list_files`](./src/mcp-server/tools/obsidianListFilesTool/)                 | Lists files 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`](./src/mcp-server/tools/obsidianManageFrontmatterTool/) | Atomically manages a note's YAML frontmatter.                   | - `get`, `set`, or `delete` frontmatter keys.- Avoids rewriting the entire file for metadata changes.                                             |
| [`obsidian_manage_tags`](./src/mcp-server/tools/obsidianManageTagsTool/)               | Adds, removes, or lists tags for a note.                        | - Manages tags in both YAML frontmatter and inline content.                                                                                            |
| [`obsidian_delete_file`](./src/mcp-server/tools/obsidianDeleteFileTool/)               | Permanently deletes a specified file from the vault.            | - Case-insensitive path fallback for safety.                                                                                                           |
| [`obsidian_dataview_query`](./src/mcp-server/tools/obsidianDataviewQueryTool/)         | Execute Dataview DQL queries against your vault.                | - Run TABLE, LIST queries using Dataview syntax.- Query notes by tags, frontmatter, dates.- Generate reports and analytics.                |
| [`obsidian_task_query`](./src/mcp-server/tools/obsidianTaskQueryTool/)                 | Search and analyze tasks across your vault.                     | - Filter by status, date ranges, priorities.- Multiple output formats.- Extract task metadata (due dates, tags).                           |

---

## Table of Contents

| [Overview](#overview) | [Features](#features) | [Installation](#installation) |
| [Configuration](#configuration) | [Project Structure](#project-structure) | [Vault Cache Service](#vault-cache-service) |
| [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#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](https://github.com/coddingtonbear/obsidian-local-rest-api) running inside your vault.

> **Developer Note**: This repository includes a [.clinerules](.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 the `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**: Native Node.js HTTP server with session management, CORS support, and API key authentication.

### 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](#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](https://github.com/coddingtonbear/obsidian-local-rest-api) 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.
5.  **Tailscale** (for remote access): Install [Tailscale](https://tailscale.com) and enable Tailscale Funnel for secure remote Claude.ai integration.

> **💡 Quick Setup**: For automatic startup on boot, see the [Auto-Start Setup Guide](./scripts/autostart/README.md) after installation.

### Installation

1.  Clone this enhanced repository:
    ```bash
    git clone https://github.com/BoweyLou/obsidian-mcp-server-enhanced.git
    cd obsidian-mcp-server-enhanced
    ```
2.  Install dependencies:
    ```bash
    npm install
    ```
3.  Build the project:
    ```bash
    npm run build
    ```
    This compiles the TypeScript code to JavaScript in the `dist/` directory and makes the entry point executable.

## Configuration

### Environment Variables

Configure the server using environment variables.

These variables must be set in the MCP client configuration (e.g., `cline_mcp_settings.json`) or in your environment before starting the server (if running directly).

If running directly, they can be set in a `.env` file in the project root or directly in your environment.

| Variable                              | Description                                               | Required          | Default                  |
| :------------------------------------ | :-------------------------------------------------------- | :---------------- | :----------------------- |
| **`MCP_AUTH_KEY`**                    | Authentication key for Claude.ai Remote MCP access. Generate with `openssl rand -hex 32` | **Yes** (Remote)  | `undefined`              |
| **`OBSIDIAN_VAULTS`**                 | JSON array of vault configurations for multi-vault mode.   | **Yes** (Multi)    | `undefined`              |
| **`OBSIDIAN_API_KEY`**                | API Key from Obsidian plugin (single-vault mode only).     | **Yes** (Single)  | `undefined`              |
| **`OBSIDIAN_BASE_URL`**               | Base URL of Obsidian API (single-vault mode only).         | **Yes** (Single)  | `http://127.0.0.1:27123` |
| `MCP_TRANSPORT_TYPE`                  | Server transport: `stdio` or `http`.                      | No                | `http`                   |
| `MCP_HTTP_PORT`                       | Port for the HTTP server.                                 | No                | `3010`                   |
| `MCP_HTTP_HOST`                       | Host for the HTTP server.                                 | No                | `127.0.0.1`              |
| `MCP_HTTP_STATELESS`                  | Enable stateless mode for Claude.ai compatibility.        | No                | `false`                  |
| `MCP_ALLOWED_ORIGINS`                 | Comma-separated origins for CORS. **Set for production.** | No                | (none)                   |
| `CHATGPT_LAYER_ENABLED`               | Set to `true` to serve the ChatGPT manifest plus JSON action endpoint. | No | `false` |
| `CHATGPT_MANIFEST_PATH`               | HTTP path that exposes the ChatGPT manifest JSON.         | No                | `/.well-known/obsidian-chatgpt-manifest.json` |
| `CHATGPT_ACTIONS_PATH`                | HTTP path for ChatGPT JSON actions (POST).                | No                | `/chatgpt/actions`       |
| `CHATGPT_FACADE_TOKEN_TTL_SECONDS`    | ChatGPT facade access-token lifetime.                     | No                | `3600`                   |
| `CHATGPT_FACADE_REFRESH_TOKEN_TTL_SECONDS` | ChatGPT facade refresh-token lifetime.                | No                | `2592000`                |
| `CHATGPT_FACADE_SCOPES`               | Comma-separated ChatGPT facade scopes. Add write scopes only for explicitly trusted clients. | No | `obsidian:read` |
| `MCP_LOG_LEVEL`                       | Logging level (`debug`, `info`, `error`, etc.).           | No                | `info`                   |
| `OBSIDIAN_VERIFY_SSL`                 | Set to `false` to disable SSL verification.               | No                | `true`                   |
| `OBSIDIAN_ENABLE_CACHE`               | Set to `true` to enable the in-memory vault cache.        | No                | `true`                   |
| `OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN` | Refresh interval for the vault cache in minutes.          | No                | `10`                     |

### Multi-Vault Configuration

The server supports both single-vault (backwards compatible) and multi-vault modes:

#### Single-Vault Mode (Legacy)
```bash
# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_API_KEY=your-obsidian-plugin-api-key
OBSIDIAN_BAS

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BoweyLou](https://github.com/BoweyLou)
- **Source:** [BoweyLou/obsidian-mcp-server-enhanced](https://github.com/BoweyLou/obsidian-mcp-server-enhanced)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-boweylou-obsidian-mcp-server-enhanced
- Seller: https://agentstack.voostack.com/s/boweylou
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.