Skip to content
Back to search

obsidian-mcp

Obsidian MCP (Model Context Protocol) Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/newtype-01--obsidian-mcp/badge.svg)](/listings/newtype-01--obsidian-mcp)

HTML

<a href="/listings/newtype-01--obsidian-mcp"><img src="/api/listings/newtype-01--obsidian-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Double-click the downloaded `.dxt` file and the system will automatically install the extension. Then fill in the configuration interface:

- **Vault Path**: Your Obsidian vault path (e.g., `/Users/username/Documents/MyVault`) - **API Token**: Obsidian Local REST API plugin token - **API Port**: API port number (default: `27123`)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 256 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Obsidian MCP (Model Context Protocol) Server
  2. English | [中文](./README.zh.md)
  3. This project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.
  4. Created by huangyihe
  5. - Prompt House: https://prompthouse.app/
  6. - YouTube: https://www.youtube.com/@huanyihe777
  7. - Twitter: https://x.com/huangyihe
  8. - Community: https://t.zsxq.com/19IaNz5wK
  9. ## Features
  10. - **🔗 Seamless Obsidian Integration**: Direct access to Obsidian knowledge bases through MCP protocol
  11. - **📝 Complete Note Management**: Read, create, update, and delete notes with advanced text replacement
  12. - **📁 Folder Operations**: Create, rename, move, and delete folders with full hierarchy support
  13. - **🔍 Intelligent Search**: Full-text search across all file types with smart scoring
  14. - **🤖 AI-Powered Analysis**: **NEW** Strategic insights using TRILEMMA-PRINCIPLES framework
  15. - **🔗 Auto Backlink Generation**: **NEW** Intelligent detection and conversion of note names to wikilinks
  16. - **⚡ Precision Editing**: Advanced PATCH operations with heading and block-level targeting
  17. - **🚀 Dual API Strategy**: Obsidian REST API with filesystem fallback for maximum reliability
  18. - **🎯 Context Optimization**: Smart content summarization for LLM context length management
  19. - **📊 Batch Processing**: Efficient bulk operations with progress tracking
  20. ## Supported Tools
  21. The MCP server provides the following comprehensive tools:
  22. ### 📋 Core Operations
  23. - `list_notes`: List notes in the Obsidian vault with optional folder filtering
  24. - **NEW** `recursive` parameter: Control whether to list files recursively in subdirectories (default: true)
  25. - Use `recursive: false` to list only files in the specified folder without subdirectories
  26. - `read_note`: Read the content of a specific note in the Obsidian vault
  27. - `read_multiple_notes`: Read content from multiple notes simultaneously for batch processing
  28. - `create_note`: Create a new note in the Obsidian vault with full content
  29. - `delete_note`: Delete a note from the Obsidian vault
  30. - `search_vault`: Advanced search across all file types with filename and content matching
  31. - `move_note`: Move or rename notes to new locations (supports all file types including PDFs)
  32. - `manage_folder`: Complete folder CRUD operations (create/rename/move/delete)
  33. ### 🚀 Advanced Features
  34. - `update_note`: **Enhanced** Update content using text replacements OR precision insertion
  35. - Traditional text replacement mode
  36. - **NEW** Heading-based insertion (before/after/append/prepend)
  37. - **NEW** Block ID-based insertion with `^block-id` support
  38. - **NEW** PATCH API integration with filesystem fallback
  39. - `auto_backlink_vault`: **🔗 Auto Backlink Generation**
  40. - Intelligently scan entire vault for note name mentions
  41. - Convert text references to wikilink format (`[[note name]]`)
  42. - Smart pattern matching with false positive prevention
  43. - Configurable dry-run mode and batch processing
  44. - `notes_insight`: **🧠 AI-Powered Strategic Analysis** ⭐ **NEW**
  45. - Generate strategic insights using TRILEMMA-PRINCIPLES framework
  46. - Automatic topic-based note discovery and relevance ranking
  47. - AI-driven content summarization for context optimization
  48. - Structured analysis: constraint identification → assumption challenges → breakthrough solutions
  49. - Configurable parameters for analysis depth and scope
  50. ## Prerequisites
  51. - Node.js (v16 or higher)
  52. - Obsidian desktop application
  53. - Obsidian Local REST API plugin (needs to be installed in Obsidian)
  54. ## Installation Options
  55. Choose the most suitable installation method based on your technical level and usage needs:
  56. | Method | Target Users | Advantages | Disadvantages |
  57. |--------|-------------|------------|---------------|
  58. | **🎯 One-Click Install (DXT)** | General users | Simplest, GUI configuration | Requires DXT-enabled client |
  59. | **📦 Remote Install (NPM)** | Node.js users | Auto-updates, no installation | Requires network connection |
  60. | **🔧 Local Deploy** | Advanced users | Offline use, full control | Manual updates required |
  61. ---
  62. ## Method 1: One-Click Install (DXT Package) - ✅ Recommended
  63. **Suitable for:** General users who want the simplest installation experience
  64. ### Step 1: Download DXT File
  65. Download the pre-built extension package: [obsidian-mcp.dxt](./obsidian-mcp.dxt)
  66. ### Step 2: Install and Configure
  67. Double-click the downloaded `.dxt` file and the system will automatically install the extension. Then fill in the configuration interface:
  68. - **Vault Path**: Your Obsidian vault path (e.g., `/Users/username/Documents/MyVault`)
  69. - **API Token**: Obsidian Local REST API plugin token
  70. - **API Port**: API port number (default: `27123`)
  71. ---
  72. ## Method 2: Remote Install (NPM Package)
  73. **Suitable for:** Node.js developers who want automatic updates and version management
  74. Simply add the following configuration to your MCP client config file:
  75. **Using npx (recommended, no pre-installation required):**
  76. ```json
  77. {
  78. "mcpServers": {
  79. "obsidian-mcp": {
  80. "command": "npx",
  81. "args": [
  82. "@huangyihe/obsidian-mcp"
  83. ],
  84. "env": {
  85. "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
  86. "OBSIDIAN_API_TOKEN": "your_api_token",
  87. "OBSIDIAN_API_PORT": "27123"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. > **Note**: First run will automatically download the package, subsequent runs use cache, ensuring you always use the latest version.
  94. ---
  95. ## Method 3: Local Deploy
  96. **Suitable for:** Users who need customization, advanced control, or offline usage
  97. ### Option A: Global Install (Recommended)
  98. **Step 1: Global Install**
  99. ```bash
  100. npm install -g @huangyihe/obsidian-mcp
  101. ```
  102. **Step 2: MCP Client Configuration**
  103. ```json
  104. {
  105. "mcpServers": {
  106. "obsidian-mcp": {
  107. "command": "obsidian-mcp",
  108. "env": {
  109. "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
  110. "OBSIDIAN_API_TOKEN": "your_api_token",
  111. "OBSIDIAN_API_PORT": "27123"
  112. }
  113. }
  114. }
  115. }
  116. ```
  117. ### Option B: Source Deploy
  118. **Step 1: Clone Repository**
  119. ```bash
  120. git clone https://github.com/newtype-01/obsidian-mcp.git
  121. cd obsidian-mcp
  122. ```
  123. **Step 2: Install Dependencies**
  124. ```bash
  125. npm install
  126. ```
  127. **Step 3: Build Project**
  128. ```bash
  129. npm run build
  130. ```
  131. **Step 4: Configure Environment Variables**
  132. ```bash
  133. cp .env.example .env
  134. # Edit .env file with your configuration
  135. ```
  136. **Step 5: Start Server**
  137. ```bash
  138. npm start
  139. ```
  140. ### Option C: Docker Deploy
  141. **Using Docker Compose (Recommended)**
  142. ```bash
  143. # Configure environment variables
  144. cp .env.example .env
  145. # Edit .env file
  146. # Start service
  147. docker-compose up -d
  148. ```
  149. **Using Docker Command**
  150. ```bash
  151. # Build image
  152. docker build -t obsidian-mcp .
  153. # Run container
  154. docker run -d \
  155. --name obsidian-mcp \
  156. --env-file .env \
  157. --network host \
  158. -v $(OBSIDIAN_VAULT_PATH):$(OBSIDIAN_VAULT_PATH) \
  159. obsidian-mcp
  160. ```
  161. ---
  162. ## Configuration Guide
  163. ### Environment Variables
  164. All installation methods require the following configuration:
  165. - `OBSIDIAN_VAULT_PATH`: Path to your Obsidian vault
  166. - `OBSIDIAN_API_TOKEN`: API token for Obsidian Local REST API plugin
  167. - `OBSIDIAN_API_PORT`: API port for Obsidian Local REST API (default: 27123)
  168. ⚠️ **Important**: For remote NPM installation and global installation, you MUST use the `OBSIDIAN_` prefix for environment variables. The variables `VAULT_PATH`, `API_TOKEN` without the prefix will not work correctly.
  169. ### Getting API Token
  170. 1. Install "Local REST API" plugin in Obsidian
  171. 2. Generate API Token in plugin settings
  172. 3. Note the port number (default 27123)
  173. ## Testing
  174. The project includes a test script to verify server functionality:
  175. ```bash
  176. node test-mcp.js
  177. ```
  178. ## Development
  179. - Use `npm run dev` to run the server in development mode
  180. - Source code is located in the `src` directory
  181. ## License
  182. MIT
  183. ## Contributing
  184. Pull Requests and Issues are welcome!
  185. ## Related Projects
  186. - [Model Context Protocol](https://github.com/anthropics/model-context-protocol)
  187. - [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.