Skip to content
Back to search

mcpvault

A lightweight Model Context Protocol (MCP) server for safe Obsidian vault access

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bitbonsai/mcpvault with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bitbonsai/mcpvault'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bitbonsai-mcpvault/badge.svg)](/listings/bitbonsai-mcpvault)

HTML

<a href="/listings/bitbonsai-mcpvault"><img src="/api/listings/bitbonsai-mcpvault/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.

1. **Install Node.js runtime:**

   # Download from https://nodejs.org (v20.0.0 or later)
   # or use a package manager like nvm, brew, apt, etc.

2. **Test the server:**

If using the published package:

   npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault

3. **Configure your AI client:**

**Claude Desktop** - Copy this to `claude_desktop_config.json`:

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
       }
     }
   }

**Claude Code** - Copy this to `~/.claude.json`:

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
         "env": {}
       }
     }
   }

**OpenCode** - Copy this to `~/.config/opencode/opencode.json`

   {
     "mcp": {
       "obsidian": {
         "type": "local",
         "command": [
           "npx",
           "@bitbonsai/mcpvault@latest",
           "/path/to/your/vault/"
         ],
         "enabled": true
       }
     }
   }

Replace `/path/to/your/vault` with your actual Obsidian vault path.

For other platforms, see [detailed configuration guides](#ai-client-configuration) below.

4. **Test with your AI:** - "List files in my Obsidian vault" - "Read my note called 'project-ideas.md'" - "Create a new note with today's date"

To verify the connection, ask your client to list MCPVault tools or read a known note.

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 · 1,021 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center"> <img width="256" height="256" alt="image" src="https://github.com/user-attachments/assets/1e21d898-811b-42c2-a810-bf921dde0f58" /> </div>
  2. # MCPVault
  3. [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fbitbonsai%2Fmcpvault.svg)](https://mcptoplist.com/server/glama%2Fbitbonsai%2Fmcpvault)
  4. A local MCP server that lets compatible clients read, search, and edit notes in an Obsidian vault. MCPVault works directly with vault files, restricts file operations to the configured vault root, and preserves formatting for unchanged frontmatter fields.
  5. <div align="center">
  6. [https://mcpvault.org](https://mcpvault.org)
  7. [Changelog](./CHANGELOG.md)
  8. </div>
  9. <div align="center">
  10. [![GitHub Stars](https://img.shields.io/github/stars/bitbonsai/mcpvault?style=flat&logo=github&logoColor=white&color=9065ea&labelColor=262626)](https://github.com/bitbonsai/mcpvault) [![npm version](https://img.shields.io/npm/v/%40bitbonsai%2Fmcpvault?style=flat&logo=npm&logoColor=white&color=9065ea&labelColor=262626)](https://www.npmjs.com/package/@bitbonsai/mcpvault) [![npm downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fmcpvault.org%2Fapi%2Fdownloads.json&style=flat&logo=npm&logoColor=white&color=9065ea&labelColor=262626)](https://www.npmjs.com/package/@bitbonsai/mcpvault) [![GitHub Sponsors](https://img.shields.io/github/sponsors/BitBonsai?style=flat&logo=github&logoColor=white&color=9065ea&labelColor=262626)](https://github.com/sponsors/bitbonsai) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-Support%20Me-9065ea?style=flat&logo=ko-fi&logoColor=white&labelColor=262626)](https://ko-fi.com/bitbonsai) [![Liberapay](https://img.shields.io/badge/Liberapay-Weekly%20Support-9065ea?style=flat&logo=liberapay&logoColor=white&labelColor=262626)](https://liberapay.com/bitbonsai/)
  11. </div>
  12. ## Supported clients
  13. Configuration examples are available for Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1+, Cursor, Windsurf, and Ontheia. Other clients can use MCPVault if they support local stdio MCP servers.
  14. https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c
  15. ## Quick start
  16. 1. **Install Node.js runtime:**
  17. ```bash
  18. # Download from https://nodejs.org (v22.12.0 or later)
  19. # or use a package manager like nvm, brew, apt, etc.
  20. ```
  21. 2. **Test the server:**
  22. If using the published package:
  23. ```bash
  24. npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
  25. ```
  26. 3. **Configure your AI client:**
  27. **Claude Desktop** - Copy this to `claude_desktop_config.json`:
  28. ```json
  29. {
  30. "mcpServers": {
  31. "obsidian": {
  32. "command": "npx",
  33. "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
  34. }
  35. }
  36. }
  37. ```
  38. **Claude Code** - Copy this to `~/.claude.json`:
  39. ```json
  40. {
  41. "mcpServers": {
  42. "obsidian": {
  43. "command": "npx",
  44. "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
  45. "env": {}
  46. }
  47. }
  48. }
  49. ```
  50. **OpenCode** - Copy this to `~/.config/opencode/opencode.json`
  51. ```json
  52. {
  53. "mcp": {
  54. "obsidian": {
  55. "type": "local",
  56. "command": [
  57. "npx",
  58. "@bitbonsai/mcpvault@latest",
  59. "/path/to/your/vault/"
  60. ],
  61. "enabled": true
  62. }
  63. }
  64. }
  65. ```
  66. Replace `/path/to/your/vault` with your actual Obsidian vault path.
  67. For other platforms, see [detailed configuration guides](#ai-client-configuration) below.
  68. 4. **Test with your AI:**
  69. - "List files in my Obsidian vault"
  70. - "Read my note called 'project-ideas.md'"
  71. - "Create a new note with today's date"
  72. To verify the connection, ask your client to list MCPVault tools or read a known note.
  73. ## How it connects
  74. An MCP client starts MCPVault as a local stdio process and passes the vault path. MCPVault exposes the same tools to each supported client, so the server is not tied to one AI provider. Obsidian does not need to be running, and no Obsidian plugin is required.
  75. ## Features
  76. - AST-aware frontmatter updates preserve formatting for unchanged YAML fields.
  77. - Path checks block traversal, symlink escapes, dotfiles, `.obsidian`, `.git`, and `node_modules`.
  78. - Eighteen MCP tools cover note and file operations:
  79. - File operations: `read_note`, `write_note`, `patch_note`, `delete_note`, `move_note`, `move_file`
  80. - Partial reads: `get_note_outline`, `read_note_lines`
  81. - Directory and batch reads: `list_directory`, `read_multiple_notes`
  82. - Search: `search_notes` with multi-word matching and BM25 reranking
  83. - Metadata and tags: `get_frontmatter`, `update_frontmatter`, `get_notes_info`, `get_vault_stats`, `manage_tags`, `list_all_tags`
  84. - Wiki links: `wiki_link` resolves names and returns alternative paths when a name is ambiguous
  85. - `write_note` supports overwrite, append, and prepend modes.
  86. - `delete_note` and `move_file` require matching confirmation paths.
  87. - Path arguments are trimmed before validation.
  88. - Search and batch tools return compact fields by default; set `prettyPrint: true` for expanded output.
  89. - The package exports TypeScript declarations and public types.
  90. - MCPVault requires no Obsidian plugin.
  91. ## Prerequisites
  92. - [Node.js](https://nodejs.org) runtime (v22.12.0 or later)
  93. - An Obsidian vault (local directory with `.md`, `.markdown`, `.txt`, `.base`, or `.canvas` files)
  94. - MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)
  95. ## Installation
  96. ### For end users
  97. `npx` downloads and runs the package:
  98. ```bash
  99. npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
  100. ```
  101. If you omit the vault path, the server uses your current working directory as the vault root.
  102. ### For developers
  103. 1. Clone this repository
  104. 2. Use the correct Node.js version:
  105. ```bash
  106. nvm use # Uses Node 24 from .nvmrc
  107. ```
  108. 3. Install dependencies with npm:
  109. ```bash
  110. npm install # Corepack automatically uses npm 10.9.0
  111. ```
  112. 4. Test locally with MCP inspector:
  113. ```bash
  114. npx @modelcontextprotocol/inspector npm start /path/to/your/vault
  115. ```
  116. Use MCP Inspector to test the server before adding it to a client:
  117. ```bash
  118. # Install globally for easier access
  119. npm install -g @modelcontextprotocol/inspector
  120. # Test with any vault
  121. mcp-inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
  122. ```
  123. ## Usage
  124. ### Running the Server
  125. **End users:**
  126. ```bash
  127. npx @bitbonsai/mcpvault@latest
  128. npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
  129. npx @bitbonsai/mcpvault@latest ./Vault
  130. ```
  131. **Developers:**
  132. ```bash
  133. npm start
  134. npm start /path/to/your/obsidian/vault
  135. npm start ./Vault
  136. ```
  137. ### AI Client Configuration
  138. #### Claude Desktop
  139. Add to your Claude Desktop configuration file:
  140. **Single Vault:**
  141. ```json
  142. {
  143. "mcpServers": {
  144. "obsidian": {
  145. "command": "npx",
  146. "args": [
  147. "@bitbonsai/mcpvault@latest",
  148. "/Users/yourname/Documents/MyVault"
  149. ]
  150. }
  151. }
  152. }
  153. ```
  154. **Multiple Vaults:**
  155. ```json
  156. {
  157. "mcpServers": {
  158. "obsidian-personal": {
  159. "command": "npx",
  160. "args": [
  161. "@bitbonsai/mcpvault@latest",
  162. "/Users/yourname/Documents/PersonalVault"
  163. ]
  164. },
  165. "obsidian-work": {
  166. "command": "npx",
  167. "args": [
  168. "@bitbonsai/mcpvault@latest",
  169. "/Users/yourname/Documents/WorkVault"
  170. ]
  171. }
  172. }
  173. }
  174. ```
  175. **Read-only mode:**
  176. Add `--read-only` after the vault path to expose only read tools. Mutating tools are omitted from discovery and rejected if called directly.
  177. ```json
  178. {
  179. "mcpServers": {
  180. "obsidian-read-only": {
  181. "command": "npx",
  182. "args": [
  183. "@bitbonsai/mcpvault@latest",
  184. "/Users/yourname/Documents/ResearchVault",
  185. "--read-only"
  186. ]
  187. }
  188. }
  189. }
  190. ```
  191. The CLI also accepts `--read-only true` and `--read-only=true` for configuration systems that require explicit values. Omit the option, or set it to `false`, to keep normal read/write access.
  192. **Default search and listing exclusions:**
  193. Repeat `--exclude <subtree>` to hide vault-relative folders from `search_notes` and `list_directory` in every session. Per-call `excludePaths` add to these defaults. Direct read and write tools remain available for excluded paths.
  194. ```json
  195. "args": [
  196. "@bitbonsai/mcpvault@latest",
  197. "/Users/yourname/Documents/ResearchVault",
  198. "--exclude", "Archive",
  199. "--exclude", "Snapshots/Old"
  200. ]
  201. ```
  202. MCPVault does not read Obsidian's `.obsidian/app.json`; exclusions stay explicit in the MCP server configuration.
  203. **Configuration File Locations:**
  204. - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  205. - **Windows:** `C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json`
  206. - **Linux:** `~/.config/Claude/claude_desktop_config.json`
  207. _You can also access this through Claude Desktop → Settings → Developer → Edit Config_
  208. #### ChatGPT Desktop
  209. **Requirements:** ChatGPT Enterprise, Education, or Team subscription (not available for individual Plus users)
  210. ChatGPT uses MCP through Deep Research and developer mode. Configuration is done through the ChatGPT interface:
  211. 1. Access ChatGPT developer mode (beta feature)
  212. 2. Configure MCP servers through the built-in MCP client
  213. 3. Create custom connectors for your organization
  214. _Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration._
  215. #### Claude Code
  216. Claude Code uses `.claude.json` configuration file:
  217. **User-scoped (recommended):** Edit `~/.claude.json`:
  218. ```json
  219. {
  220. "mcpServers": {
  221. "obsidian": {
  222. "command": "npx",
  223. "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
  224. "env": {}
  225. }
  226. }
  227. }
  228. ```
  229. **Project-scoped:** Edit `.claude.json` in your project or add to the projects section:
  230. ```json
  231. {
  232. "projects": {
  233. "/path/to/your/project": {
  234. "mcpServers": {
  235. "obsidian": {
  236. "command": "npx",
  237. "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
  238. }
  239. }
  240. }
  241. }
  242. }
  243. ```
  244. **Using Claude Code CLI:**
  245. ```bash
  246. claude mcp add obsidian --scope user npx @bitbonsai/mcpvault /path/to/your/vault
  247. ```
  248. #### Goose Desktop
  249. On Goose Desktop settings, click **Add custom extension**, and on the command field add:
  250. ```bash
  251. npx @bitbonsai/mcpvault@latest /path/to/your/vault
  252. ```
  253. #### Other MCP-Compatible Clients (2025)
  254. **Confirmed MCP Support:**
  255. - **IntelliJ IDEA 2025.1+** - Native MCP client support
  256. - **Cursor IDE** - Built-in MCP compatibility
  257. - **Windsurf IDE** - Full MCP integration
  258. - **[Ontheia](https://ontheia.ai)** - Self-hosted, open-source AI agent platform
  259. - **Zed, Replit, Codeium, Sourcegraph** - In development
  260. - **Microsoft Copilot Studio** - Native MCP support with one-click server connections
  261. Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.
  262. ### Examples
  263. #### Ask your AI assistant about your notes:
  264. - "What files are in my Obsidian vault?"
  265. - "Read my note called 'project-ideas.md'"
  266. - "Show me all notes with 'AI' in the title"
  267. #### Have your AI assistant help with note management:
  268. - "Create a new note called 'meeting-notes.md' with today's date in the frontmatter"
  269. - "Append today's journal entry to my daily note"
  270. - "Prepend an urgent task to my todo list"
  271. - "Add the tags 'project' and 'urgent' to my task note"
  272. - "List all tags in my research note"
  273. - "Remove the 'draft' tag from my completed article"
  274. - "List all markdown files in my 'Projects' folder"
  275. - "Delete the old draft note 'draft-ideas.md' (with confirmation)"
  276. #### Example workflows
  277. - "Summarize my research notes tagged with 'machine-learning' from the last month"
  278. - "Update the status in my project notes to 'completed' and add today's date"
  279. - "Find notes that mention 'API design' and draft a guide from them"
  280. - "Review my untagged notes and suggest tags based on their content"
  281. ## Troubleshooting
  282. ### Common Issues
  283. #### "command not found: npx"
  284. - **Solution:** Install Node.js runtime from [nodejs.org](https://nodejs.org)
  285. - **Alternative:** Use global install: `npm install -g @bitbonsai/mcpvault`
  286. #### "File not found" when paths look correct
  287. - **Cause:** The server is using the wrong vault root
  288. - **Solution:** Either run the command from your vault directory or pass the vault path explicitly
  289. #### "Permission denied" errors
  290. - **Cause:** Insufficient file system permissions
  291. - **Solution:** Ensure the vault directory is readable/writable by your user
  292. #### "Path traversal not allowed"
  293. - **Cause:** Trying to access files outside the vault
  294. - **Solution:** All file paths must be relative to the vault root
  295. #### AI client not recognizing the server
  296. 1. Check the configuration file path is correct for your OS
  297. 2. Ensure JSON syntax is valid (use a JSON validator)
  298. 3. Restart your AI client after configuration changes
  299. 4. Check your AI client's logs for error messages
  300. 5. Verify your AI client supports MCP (Model Context Protocol)
  301. #### ".obsidian files still showing up"
  302. - **Expected:** The path filter automatically excludes `.obsidian/**` patterns
  303. - **If still seeing them:** The filter is working as designed for security
  304. ### Debug Mode
  305. Run with error logging:
  306. ```bash
  307. npx @bitbonsai/mcpvault /path/to/vault 2>debug.log
  308. ```
  309. ### Getting Help
  310. - [Open an issue](https://github.com/bitbonsai/mcpvault/issues) on GitHub
  311. - Include your OS, Node.js version, and error messages
  312. - Provide the vault directory structure (without sensitive content)
  313. ## Testing
  314. Run the test suite:
  315. ```bash
  316. npm test
  317. ```
  318. ## API Methods
  319. ### `read_note`
  320. Read a note from the vault with parsed frontmatter.
  321. **Request:**
  322. ```json
  323. {
  324. "name": "read_note",
  325. "arguments": {
  326. "path": "project-ideas.md",
  327. "prettyPrint": false
  328. }
  329. }
  330. ```
  331. **Compact response:**
  332. ```json
  333. {
  334. "fm": {
  335. "title": "Project Ideas",
  336. "tags": ["projects", "brainstorming"],
  337. "created": "2023-01-15T10:30:00.000Z"
  338. },
  339. "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
  340. }
  341. ```
  342. **Response (with prettyPrint: true):**
  343. ```json
  344. {
  345. "fm": {
  346. "title": "Project Ideas",
  347. "tags": ["projects", "brainstorming"],
  348. "created": "2023-01-15T10:30:00.000Z"
  349. },
  350. "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
  351. }
  352. ```
  353. ### `write_note`
  354. Write a note to the vault with optional frontmatter and write mode.
  355. **Write Modes:**
  356. - `overwrite` (default): Replace entire file content
  357. - `append`: Add content to the end of existing file
  358. - `prepend`: Add content to the beginning of existing file
  359. **Request (Overwrite):**
  360. ```json
  361. {
  362. "name": "write_note",
  363. "arguments": {
  364. "path": "meeting-notes.md",
  365. "content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
  366. "frontmatter": {
  367. "title": "Team Meeting Notes",
  368. "date": "2023-12-01",
  369. "tags": ["meetings", "team"]
  370. },
  371. "mode": "overwrite"
  372. }
  373. }
  374. ```
  375. **Request (Append):**
  376. ```json
  377. {
  378. "name": "write_note",
  379. "arguments": {
  380. "path": "daily-log.md",
  381. "content": "\n\n## 3:00 PM Update\n- Completed project review\n- Started new feature",
  382. "mode": "append"
  383. }
  384. }
  385. ```
  386. **Response:**
  387. ```json
  388. {
  389. "message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
  390. }
  391. ```
  392. ### `patch_note`
  393. Replace an exact string inside an existing note without rewriting the full file.
  394. **Request:**
  395. ```json
  396. {
  397. "name": "patch_note",
  398. "arguments": {
  399. "path": "meeting-notes.md",
  400. "oldString": "- Next milestones",
  401. "newString": "- Next milestones (owner: Alex)",
  402. "replaceAll": false
  403. }
  404. }
  405. ```
  406. **Response (success):**
  407. ```json
  408. {
  409. "success": true,
  410. "path": "meeting-notes.md",
  411. "message": "Successfully replaced 1 occurrence",
  412. "matchCount": 1
  413. }
  414. ```
  415. **Response (multiple matches with replaceAll=false):**
  416. ```json
  417. {
  418. "success": false,
  419. "path": "meeting-notes.md",
  420. "message": "Found 3 occurrences of the string. Use replaceAll=true to replace all occurrences, or provide a more specific string to match exactly one occurrence.",
  421. "matchCount": 3
  422. }
  423. ```
  424. ### `list_directory`
  425. List files and directories in the vault.
  426. Note: this includes non-note filenames (for example `pdf`, `png`, `jpg`) so AI assistants can see vault structure, but note tools like `read_note` and `write_note` still operate on note files only (`.md`, `.markdown`, `.txt`, `.base`, `.canvas`).
  427. **Request:**
  428. ```json
  429. {
  430. "name": "list_directory",
  431. "arguments": {
  432. "path": "Projects",
  433. "prettyPrint": false
  434. }
  435. }
  436. ```
  437. **Compact response:**
  438. ```json
  439. {
  440. "dirs": ["AI-Tools", "Web-Development"],
  441. "files": ["project-template.md", "roadmap.md"]
  442. }
  443. ```
  444. ### `delete_note`
  445. Delete a note from the vault (requires confirmation for safety).
  446. **Request:**
  447. ```json
  448. {
  449. "name": "delete_note",
  450. "arguments": {
  451. "path": "old-draft.md",
  452. "confirmPath": "old-draft.md",
  453. "trashMode": "local"
  454. }
  455. }
  456. ```
  457. **Response (Success):**
  458. ```json
  459. {
  460. "success": true,
  461. "path": "old-draft.md",
  462. "message": "Successfully moved note to vault trash: old-draft.md"
  463. }
  464. ```
  465. **Trash modes:**
  466. - `none` (default): permanent delete
  467. - `local`: move to `.trash` inside the vault, preserving folder structure
  468. - `system`: move to the OS trash/recycle bin
  469. **Response (Confirmation Failed):**
  470. ```json
  471. {
  472. "success": false,
  473. "path": "old-draft.md",
  474. "message": "Deletion cancelled: confirmation path does not match. For safety, both 'path' and 'confirmPath' must be identical."
  475. }
  476. ```
  477. **Confirmation:** `confirmPath` must exactly match `path` before deletion proceeds.
  478. ### `get_frontmatter`
  479. Extract only the frontmatter from a note without reading the full content.
  480. **Request:**
  481. ```json
  482. {
  483. "name": "get_frontmatter",
  484. "arguments": {
  485. "path": "project-ideas.md",
  486. "prettyPrint": false
  487. }
  488. }
  489. ```
  490. **Compact response, returning frontmatter directly:**
  491. ```json
  492. {
  493. "title": "Project Ideas",
  494. "tags": ["projects", "brainstorming"],
  495. "created": "2023-01-15T10:30:00.000Z"
  496. }
  497. ```
  498. ### `manage_tags`
  499. Add, remove, or list tags in a note. Tags are managed in the frontmatter and inline tags are detected.
  500. **Request (List Tags):**
  501. ```json
  502. {
  503. "name": "manage_tags",
  504. "arguments": {
  505. "path": "research-notes.md",
  506. "operation": "list"
  507. }
  508. }
  509. ```
  510. **Request (Add Tags):**
  511. ```json
  512. {
  513. "name": "manage_tags",
  514. "arguments": {
  515. "path": "research-notes.md",
  516. "operation": "add",
  517. "tags": ["machine-learning", "ai", "important"]
  518. }
  519. }
  520. ```
  521. **Request (Remove Tags):**
  522. ```json
  523. {
  524. "name": "manage_tags",
  525. "arguments": {
  526. "path": "research-notes.md",
  527. "operation": "remove",
  528. "tags": ["draft", "temporary"]
  529. }
  530. }
  531. ```
  532. **Response:**
  533. ```json
  534. {
  535. "path": "research-notes.md",
  536. "operation": "add",
  537. "tags": ["research", "ai", "machine-learning", "important"],
  538. "success": true,
  539. "message": "Successfully added tags"
  540. }
  541. ```
  542. ### `search_notes`
  543. Search for notes in the vault by content or frontmatter with multi-word matching and BM25 relevance reranking.
  544. **Request:**
  545. ```json
  546. {
  547. "name": "search_notes",
  548. "arguments": {
  549. "query": "machine learning",
  550. "limit": 5,
  551. "searchContent": true,
  552. "searchFrontmatter": false,
  553. "caseSensitive": false,
  554. "prettyPrint": false
  555. }
  556. }
  557. ```
  558. **Compact response:**
  559. ```json
  560. [
  561. {
  562. "p": "ai-research.md",
  563. "t": "AI Research Notes",
  564. "ex": "...machine learning...",
  565. "mc": 2,
  566. "ln": 15,
  567. "uri": "obsidian://open?vault=MyVault&file=ai-research.md"
  568. }
  569. ]
  570. ```
  571. **Field names:**
  572. - `p` = path
  573. - `t` = title
  574. - `ex` = excerpt (21 chars context)
  575. - `mc` = match count
  576. - `ln` = line number
  577. - `uri` = Obsidian deep link for quick opening
  578. ### `move_note`
  579. Move or rename a note in the vault (`.md`, `.markdown`, `.txt`, `.base`, `.canvas`).
  580. **Request:**
  581. ```json
  582. {
  583. "name": "move_note",
  584. "arguments": {
  585. "oldPath": "drafts/article.md",
  586. "newPath": "published/article.md",
  587. "overwrite": false
  588. }
  589. }
  590. ```
  591. **Response:**
  592. ```json
  593. {
  594. "success": true,
  595. "oldPath": "drafts/article.md",
  596. "newPath": "published/article.md",
  597. "message": "Successfully moved note from drafts/article.md to published/article.md"
  598. }
  599. ```
  600. ### `move_file`
  601. Move or rename any file in the vault with binary-safe file operations (file-only; not recursive directory moves). For safety, this tool requires confirmation of both source and destination paths.
  602. **Request:**
  603. ```json
  604. {
  605. "name": "move_file",
  606. "arguments": {
  607. "oldPath": "Miro/attachments/Pasted image 20250812140124.png",
  608. "newPath": "assets/images/Pasted image 20250812140124.png",
  609. "confirmOldPath": "Miro/attachments/Pasted image 20250812140124.png",
  610. "confirmNewPath": "assets/images/Pasted image 20250812140124.png",
  611. "overwrite": false
  612. }
  613. }
  614. ```
  615. **Response:**
  616. ```json
  617. {
  618. "success": true,
  619. "oldPath": "Miro/attachments/Pasted image 20250812140124.png",
  620. "newPath": "assets/images/Pasted image 20250812140124.png",
  621. "message": "Successfully moved file from Miro/attachments/Pasted image 20250812140124.png to assets/images/Pasted image 20250812140124.png"
  622. }
  623. ```
  624. **Confirmation:** `confirmOldPath` must match `oldPath`, and `confirmNewPath` must match `newPath`.
  625. ### `read_multiple_notes`
  626. Read multiple notes in a batch (maximum 10 files).
  627. **Request:**
  628. ```json
  629. {
  630. "name": "read_multiple_notes",
  631. "arguments": {
  632. "paths": ["note1.md", "note2.md", "note3.md"],
  633. "includeContent": true,
  634. "includeFrontmatter": true,
  635. "prettyPrint": false
  636. }
  637. }
  638. ```
  639. **Compact response:**
  640. ```json
  641. {
  642. "ok": [
  643. {
  644. "path": "note1.md",
  645. "frontmatter": { "title": "Note 1" },
  646. "content": "# Note 1\n\nContent here..."
  647. }
  648. ],
  649. "err": [{ "path": "note2.md", "error": "File not found" }]
  650. }
  651. ```
  652. **Field names:**
  653. - `ok` = successful reads
  654. - `err` = failed reads
  655. ### `update_frontmatter`
  656. Update frontmatter of a note without changing content.
  657. **Request:**
  658. ```json
  659. {
  660. "name": "update_frontmatter",
  661. "arguments": {
  662. "path": "research-note.md",
  663. "frontmatter": {
  664. "status": "completed",
  665. "updated": "2025-09-23"
  666. },
  667. "merge": true
  668. }
  669. }
  670. ```
  671. **Response:**
  672. ```json
  673. {
  674. "message": "Successfully updated frontmatter for: research-note.md"
  675. }
  676. ```
  677. ### `get_notes_info`
  678. Get metadata for notes without reading full content.
  679. **Request:**
  680. ```json
  681. {
  682. "name": "get_notes_info",
  683. "arguments": {
  684. "paths": ["note1.md", "note2.md"],
  685. "prettyPrint": false
  686. }
  687. }
  688. ```
  689. **Compact response, returning an array directly:**
  690. ```json
  691. [
  692. {
  693. "path": "note1.md",
  694. "size": 1024,
  695. "modified": 1695456000000,
  696. "hasFrontmatter": true
  697. }
  698. ]
  699. ```
  700. ### `get_vault_stats`
  701. Get high-level vault statistics without reading note contents.
  702. **Request:**
  703. ```json
  704. {
  705. "name": "get_vault_stats",
  706. "arguments": {
  707. "recentCount": 5,
  708. "prettyPrint": false
  709. }
  710. }
  711. ```
  712. **Compact response:**
  713. ```json
  714. {
  715. "notes": 1248,
  716. "folders": 76,
  717. "size": 18349210,
  718. "recent": [
  719. {
  720. "path": "Daily/2026-02-27.md",
  721. "modified": 1772188800000,
  722. "size": 2814
  723. }
  724. ]
  725. }
  726. ```
  727. ## Security boundaries
  728. MCPVault applies these checks before file operations:
  729. ### Path Security
  730. - **Path Traversal Protection:** All file paths are validated to prevent access outside the vault
  731. - **Relative Path Enforcement:** Paths are normalized and restricted to the vault directory
  732. - **Symbolic Link Safety:** Resolved paths are checked against vault boundaries
  733. ### File Filtering
  734. - **Automatic Exclusions:** `.obsidian`, `.git`, `node_modules`, and system files are filtered
  735. - **Extension Whitelist:** Only `.md`, `.markdown`, `.txt`, `.base`, and `.canvas` files are accessible by default
  736. - **Hidden File Protection:** Dot files and system directories are automatically excluded
  737. ### Content Validation
  738. - **YAML Frontmatter Validation:** Frontmatter is parsed and validated before writing
  739. - **Function/Symbol Prevention:** Dangerous JavaScript objects are blocked from frontmatter
  740. - **Data Type Checking:** Only safe data types (strings, numbers, arrays, objects) allowed
  741. ### Best Practices
  742. - **Least Privilege:** Server only accesses the specified vault directory
  743. - **Read-Only Mode:** Run with `--read-only` for sensitive vaults; mutating tools are hidden and rejected
  744. - **Backup Recommended:** Always backup your vault before using write operations
  745. - **Network Isolation:** Server uses stdio transport (no network exposure)
  746. ### What's NOT Protected
  747. - **File Content:** The server can read/write any allowed file content
  748. - **Vault Structure:** Directory structure is visible to AI assistants
  749. - **File Metadata:** Creation times, file sizes, etc. are accessible
  750. Only grant write access to clients and conversations you trust. Use `--read-only` when the client does not need to modify notes.
  751. ## Architecture
  752. - `server.ts` - MCP server entry point
  753. - `src/cli.ts` - CLI option parsing for vault path, read-only mode, and default exclusions
  754. - `src/createServer.ts` - MCP tool registration, request routing, and discovery defaults
  755. - `src/frontmatter.ts` - YAML frontmatter handling with gray-matter, preserving formatting and CRLF line endings; executable JavaScript frontmatter stays inert as note content
  756. - `src/filesystem.ts` - File operations with path validation
  757. - `src/pathfilter.ts` - Directory and file filtering
  758. - `src/search.ts` - Note search functionality with content and frontmatter support
  759. - `src/uri.ts` - Obsidian URI generation for deep links
  760. - `src/types.ts` - TypeScript type definitions
  761. - `scripts/release.mjs` - Repository release command with readiness checks and explicit publishing authorization
  762. ## Contributing
  763. 1. Fork the repository
  764. 2. Create a feature branch: `git checkout -b feature-name`
  765. 3. Make your changes and add tests
  766. 4. Ensure all tests pass: `npm test`
  767. 5. Submit a pull request
  768. Maintainers: run `npm run release` from prepared `main` to create the GitHub Release that triggers npm publishing. Add `-- --yes` for approved automation, or `-- --check` for a read-only preview. See [RELEASING.md](RELEASING.md).
  769. ## License
  770. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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