Skip to content
Back to search

obsidian-mcp-plugin

High-performance Model Context Protocol (MCP) server for Obsidian that provides AI tools with direct vault access through semantic operations and HTTP transport.

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/aaronsb/obsidian-mcp-plugin 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/aaronsb/obsidian-mcp-plugin'

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/aaronsb--obsidian-mcp-plugin/badge.svg)](/listings/aaronsb--obsidian-mcp-plugin)

HTML

<a href="/listings/aaronsb--obsidian-mcp-plugin"><img src="/api/listings/aaronsb--obsidian-mcp-plugin/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.

**Prerequisites:** an MCP-compatible AI client like Claude Desktop, Claude Code, or Continue.dev.

> ## πŸ“¦ ──drag──▢ πŸ€–πŸ’¬ > **Download the `.mcpb` bundle from the plugin's config page β†’ drag it onto Claude Desktop β†’ paste your key. Done.**

For most people that's the entire setup. The numbered steps below spell it out, then cover other MCP clients.

1. Install the Plugin

**Via Obsidian Community Plugins** - Open Settings β†’ Community plugins β†’ Browse - Search for "Semantic Notes Vault MCP" - Install and enable β€” or install straight from the [plugin listing](https://community.obsidian.md/plugins/semantic-vault-mcp)

**Via BRAT** (for beta testing) - Install [BRAT](https://github.com/TfTHacker/obsidian42-brat) - Add beta plugin: `aaronsb/obsidian-mcp-plugin`

2. Configure Your AI Client

Three onboarding paths, ordered by audience. All three are also shown in the plugin's Settings tab with copy-ready values.

**πŸ“¦ β†’ πŸ€– Claude Desktop β€” one-click `.mcpb` install (recommended)**

Download `obsidian-mcp-<version>.mcpb` β€” either from the plugin's **Settings** tab (button right on the config page) or the [latest release](https://github.com/aaronsb/obsidian-mcp-plugin/releases/latest) β€” then either drag it onto the Claude Desktop window or double-click it. Claude Desktop opens an install dialog with two fields β€” paste the URL and API key shown in the plugin's Settings tab, hit Save, and you're done.

> *Cross-platform note:* `.mcpb` files install via Claude Desktop's bundled handler. If double-click doesn't trigger Claude on your system, drag the file onto Claude Desktop's window instead, or right-click β†’ "Open with…" and pick Claude Desktop (then "always open with" if your OS asks). Behavior varies by platform: macOS usually auto-associates, Windows may need a one-time association, Linux varies by desktop environment.

**Claude Code** β€” one command (copy the ready-made version with your API key from the plugin's Settings tab):

claude mcp add --transport http obsidian http://localhost:3001/mcp --header "Authorization: Bearer YOUR_API_KEY"

For HTTPS, use `https://localhost:3443/mcp` instead β€” see [Trusting the self-signed certificate](#trusting-the-self-signed-certificate) below. **Claude Code runs on Bun, which does not read the macOS system keychain**, so you will need to set `NODE_EXTRA_CA_CERTS`.

**Other MCP clients (Cline, Continue, custom integrations, multi-vault setups)**

Add an entry to the client's MCP config file β€” one entry per vault if you run multiple Obsidian instances on different ports:

{
  "mcpServers": {
    "obsidian-vault": {
      "transport": {
        "type": "http",
        "url": "http://localhost:3001/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

**Advanced: custom `.mcpb` per vault**

For multi-vault setups that want one-click install per vault, clone this repo and run the maker:

node scripts/make-mcpb.mjs
# Prompts for display name, URL, and API key
# Outputs obsidian-mcp-<slug>.mcpb with everything pre-filled

Drop the resulting bundle into Claude Desktop and click Install β€” no fields to type.

Trusting the self-signed certificate

The plugin's HTTPS server uses a self-signed certificate auto-generated on first start and stored under `.obsidian/plugins/semantic-vault-mcp/certificates/default.crt` inside your vault. MCP clients reject self-signed certificates by default, so you need to explicitly trust it before connecting over HTTPS. Pick the method that matches your client runtime.

**macOS Keychain** (for clients that use the system trust store β€” Claude Desktop, browser-based tools, Node with `--use-system-ca`):

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  /path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt

**`NODE_EXTRA_CA_CERTS`** (required for Claude Code and other Bun-based runtimes):

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 Β· 237 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. # Semantic Notes Vault MCP
  2. ![GitHub stars](https://img.shields.io/github/stars/aaronsb/obsidian-mcp-plugin?style=social)
  3. ![GitHub forks](https://img.shields.io/github/forks/aaronsb/obsidian-mcp-plugin?style=social)
  4. ![Downloads](https://img.shields.io/github/downloads/aaronsb/obsidian-mcp-plugin/total?color=blue)
  5. ![Latest Release](https://img.shields.io/github/v/release/aaronsb/obsidian-mcp-plugin?include_prereleases&label=version)
  6. ![License](https://img.shields.io/github/license/aaronsb/obsidian-mcp-plugin)
  7. πŸ“¦ **[Available in the Obsidian Community Plugin directory β†’](https://community.obsidian.md/plugins/semantic-vault-mcp)**
  8. **Read, write, search, and traverse your Obsidian vault from any AI assistant β€” through an MCP server that runs _inside_ Obsidian.**
  9. No external Node process to launch, no separate REST-API plugin to bridge through: the server *is* the plugin. Setup is a drag-and-drop β€” drop the `.mcpb` bundle onto Claude Desktop, paste your key, done.
  10. It exposes **8 powerful tools** β€” each a whole family of operations, not a single call (the `vault` tool alone handles 13: list, read, create, search, move, split, combine, and more) β€” with first-class **Dataview** and **Bases** support plus graph traversal across links, tags, and backlinks. And every operation respects the permissions *you* set β€” a read-only mode, per-operation controls, and path allow/block lists β€” so the AI only ever does what you've allowed, not unrestricted run of your vault.
  11. **Works with any MCP-compatible client** β€” Claude Desktop, Claude Code, Cline, Continue.dev, and anything that speaks local MCP.
  12. > **New to MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) is the open standard that lets AI assistants interact with external tools and data. You don't need to understand it to use this β€” the [Quick Start](#quick-start) is three steps.
  13. ## Quick Start
  14. **Prerequisites:** an MCP-compatible AI client like Claude Desktop, Claude Code, or Continue.dev.
  15. > ## πŸ“¦ ──drag──▢ πŸ€–πŸ’¬
  16. > **Download the `.mcpb` bundle from the plugin's config page β†’ drag it onto Claude Desktop β†’ paste your key. Done.**
  17. For most people that's the entire setup. The numbered steps below spell it out, then cover other MCP clients.
  18. ### 1. Install the Plugin
  19. **Via Obsidian Community Plugins**
  20. - Open Settings β†’ Community plugins β†’ Browse
  21. - Search for "Semantic Notes Vault MCP"
  22. - Install and enable β€” or install straight from the [plugin listing](https://community.obsidian.md/plugins/semantic-vault-mcp)
  23. **Via BRAT** (for beta testing)
  24. - Install [BRAT](https://github.com/TfTHacker/obsidian42-brat)
  25. - Add beta plugin: `aaronsb/obsidian-mcp-plugin`
  26. ### 2. Configure Your AI Client
  27. Three onboarding paths, ordered by audience. All three are also shown in the plugin's Settings tab with copy-ready values.
  28. **πŸ“¦ β†’ πŸ€– Claude Desktop β€” one-click `.mcpb` install (recommended)**
  29. Download `obsidian-mcp-<version>.mcpb` β€” either from the plugin's **Settings** tab (button right on the config page) or the [latest release](https://github.com/aaronsb/obsidian-mcp-plugin/releases/latest) β€” then either drag it onto the Claude Desktop window or double-click it. Claude Desktop opens an install dialog with two fields β€” paste the URL and API key shown in the plugin's Settings tab, hit Save, and you're done.
  30. > *Cross-platform note:* `.mcpb` files install via Claude Desktop's bundled handler. If double-click doesn't trigger Claude on your system, drag the file onto Claude Desktop's window instead, or right-click β†’ "Open with…" and pick Claude Desktop (then "always open with" if your OS asks). Behavior varies by platform: macOS usually auto-associates, Windows may need a one-time association, Linux varies by desktop environment.
  31. **Claude Code** β€” one command (copy the ready-made version with your API key from the plugin's Settings tab):
  32. ```bash
  33. claude mcp add --transport http obsidian http://localhost:3001/mcp --header "Authorization: Bearer YOUR_API_KEY"
  34. ```
  35. For HTTPS, use `https://localhost:3443/mcp` instead β€” see [Trusting the self-signed certificate](#trusting-the-self-signed-certificate) below. **Claude Code runs on Bun, which does not read the macOS system keychain**, so you will need to set `NODE_EXTRA_CA_CERTS`.
  36. **Other MCP clients (Cline, Continue, custom integrations, multi-vault setups)**
  37. Add an entry to the client's MCP config file β€” one entry per vault if you run multiple Obsidian instances on different ports:
  38. ```json
  39. {
  40. "mcpServers": {
  41. "obsidian-vault": {
  42. "transport": {
  43. "type": "http",
  44. "url": "http://localhost:3001/mcp",
  45. "headers": {
  46. "Authorization": "Bearer YOUR_API_KEY"
  47. }
  48. }
  49. }
  50. }
  51. }
  52. ```
  53. **Advanced: custom `.mcpb` per vault**
  54. For multi-vault setups that want one-click install per vault, clone this repo and run the maker:
  55. ```bash
  56. node scripts/make-mcpb.mjs
  57. # Prompts for display name, URL, and API key
  58. # Outputs obsidian-mcp-<slug>.mcpb with everything pre-filled
  59. ```
  60. Drop the resulting bundle into Claude Desktop and click Install β€” no fields to type.
  61. ### Trusting the self-signed certificate
  62. The plugin's HTTPS server uses a self-signed certificate auto-generated on first start and stored under `.obsidian/plugins/semantic-vault-mcp/certificates/default.crt` inside your vault. MCP clients reject self-signed certificates by default, so you need to explicitly trust it before connecting over HTTPS. Pick the method that matches your client runtime.
  63. **macOS Keychain** (for clients that use the system trust store β€” Claude Desktop, browser-based tools, Node with `--use-system-ca`):
  64. ```bash
  65. sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  66. /path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt
  67. ```
  68. **`NODE_EXTRA_CA_CERTS`** (required for Claude Code and other Bun-based runtimes):
  69. Bun does **not** consult the macOS system keychain for TLS trust, so trusting the certificate via Keychain Access alone has no effect β€” this is almost always the real reason an HTTPS connection from Claude Code fails. Bun only honors certificates listed in `NODE_EXTRA_CA_CERTS`:
  70. ```bash
  71. # Point directly at the plugin cert, or append it to an existing CA bundle:
  72. export NODE_EXTRA_CA_CERTS=/path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt
  73. # Propagate to GUI apps launched from the macOS dock (including Claude Code):
  74. launchctl setenv NODE_EXTRA_CA_CERTS /path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt
  75. ```
  76. Re-run these whenever the plugin regenerates its certificate (e.g. after the 1-year validity expires).
  77. > **Avoid `NODE_TLS_REJECT_UNAUTHORIZED=0`.** It disables TLS verification process-wide β€” for *every* HTTPS connection the client makes, not just this plugin β€” and masks legitimate certificate problems (expired, revoked, tampered). Trust the certificate explicitly instead.
  78. ### 3. Start Using
  79. Once connected, simply chat with your AI assistant about your notes! For example:
  80. - "What are my recent thoughts on project X?"
  81. - "Find connections between my psychology and philosophy notes"
  82. - "Summarize my meeting notes from this week"
  83. - "Create a new note linking my ideas about Y"
  84. Your AI assistant now has these capabilities:
  85. - Navigate your vault's link structure
  86. - Search and rank across all notes
  87. - Read, edit, and create notes
  88. - Analyze your knowledge graph
  89. - Work with Dataview queries (if installed)
  90. - Manage Obsidian Bases (database views)
  91. ## Why It's Different
  92. Traditional file access gives AI a narrow view β€” one document at a time. This plugin gives it the whole connected picture:
  93. - **Graph Navigation**: AI follows links between notes, understanding relationships and context
  94. - **Concept Discovery**: Search and graph traversal surface related ideas across your vault
  95. - **Contextual Awareness**: AI understands where information lives in your knowledge structure
  96. - **Intelligent Synthesis**: Combine fragments from multiple notes to answer complex questions
  97. ## Core Tools
  98. The plugin provides 8 powerful tools that give AI comprehensive vault access β€” each one a family of related operations, all subject to the permissions you set:
  99. | Tool | Purpose | Key Actions |
  100. |------|---------|-------------|
  101. | **πŸ“ vault** | File operations | list, read, create, search, move, split, combine |
  102. | **✏️ edit** | Content modification | window editing, append, patch sections |
  103. | **πŸ‘οΈ view** | Content display | view files, windows, active note |
  104. | **πŸ•ΈοΈ graph** | Link navigation | traverse, find paths, analyze connections |
  105. | **πŸ’‘ workflow** | Contextual hints | suggest next actions based on state |
  106. | **πŸ“Š dataview** | Query notes | Execute DQL queries (if installed) |
  107. | **πŸ—ƒοΈ bases** | Database views | Query and export Bases (if available) |
  108. | **ℹ️ system** | Vault info | Server status, commands, web fetch (off by default), running allowlisted commands (off by default) |
  109. ## Documentation
  110. Detailed documentation for each tool and feature:
  111. - [πŸ“ Vault Operations](docs/tools/vault.md) - File management and search
  112. - [πŸ•ΈοΈ Graph Navigation](docs/tools/graph.md) - Link traversal and analysis
  113. - [ℹ️ System Operations](docs/tools/system.md) - Server info, web fetch, and gated command execution
  114. - [πŸ”§ Configuration](#plugin-settings) - Server settings and options
  115. - [❓ Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
  116. ## In Practice
  117. This plugin doesn't just give AI access to files β€” it lets AI work across your vault as a connected whole:
  118. ### Example: Research Assistant
  119. ```
  120. User: "Summarize my research on machine learning optimization"
  121. AI uses these tools to:
  122. 1. Search for notes with ML optimization concepts
  123. 2. Traverse graph to find related papers and techniques
  124. 3. Follow backlinks to discover applications
  125. 4. Synthesize findings from multiple connected notes
  126. ```
  127. ### Example: Knowledge Explorer
  128. ```
  129. User: "What connections exist between my notes on philosophy and cognitive science?"
  130. AI uses graph tools to:
  131. 1. Find notes tagged with both topics
  132. 2. Analyze shared concepts via graph traversal
  133. 3. Identify bridge notes that connect domains
  134. 4. Map the conceptual overlap
  135. ```
  136. ## Features
  137. ### Full-Text Search
  138. - Advanced query operators: `tag:`, `path:`, `content:`
  139. - Regular expressions and phrase matching
  140. - Relevance ranking and snippet extraction
  141. ### Graph Intelligence
  142. - Multi-hop traversal with depth control
  143. - Backlink and forward-link analysis
  144. - Path finding between concepts
  145. - Tag-based navigation
  146. ### Content Operations
  147. - Fuzzy text matching for edits
  148. - Structure-aware modifications (headings, blocks)
  149. - Batch operations (split, combine, move)
  150. - Template support
  151. ### Integration
  152. - Dataview query execution
  153. - Bases database operations
  154. - Web content fetching
  155. - Read-only mode for safety
  156. ## Plugin Settings
  157. Access settings via: Settings β†’ Community plugins β†’ Semantic Notes Vault MCP
  158. Key configuration options:
  159. - **Server Ports**: HTTP (3001) and HTTPS (3443)
  160. - **Authentication**: API key protection
  161. - **Security**: Path validation and permissions
  162. - **Performance**: Connection pooling and caching
  163. ## Support
  164. - **Issues**: [GitHub Issues](https://github.com/aaronsb/obsidian-mcp-plugin/issues)
  165. - **Discussions**: [GitHub Discussions](https://github.com/aaronsb/obsidian-mcp-plugin/discussions)
  166. - **Sponsor**: [GitHub Sponsors](https://github.com/sponsors/aaronsb)
  167. ## License
  168. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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