Semantic Notes Vault MCP: an MCP server that runs inside Obsidian
High-performance Model Context Protocol (MCP) server for Obsidian that provides AI tools with direct vault access through semantic operations and HTTP transport.
At a glance
- What is it?
- The plugin puts an HTTP MCP server in the Obsidian process itself, so AI clients reach the vault without a separate Node process or a REST bridge. The interesting part is the permission model and the certificate handling; the awkward part is HTTPS trust and multi-vault setups.
- Who is it for?
- Adopt it if you already run Obsidian on the same machine as your MCP client and want vault access without a second process. Skip it if you need a headless vault server, remote access, or one client entry that spans several vaults.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The process boundary this plugin removes
Most Obsidian integrations ask you to run something next to Obsidian: a Node process that reads the vault directory from disk, or a companion plugin that exposes a REST API for a bridge to call. Semantic Notes Vault MCP takes the other route. The README states the server is the plugin, running inside Obsidian and reached over HTTP. That removes an entire class of failure. There is no second process to keep alive, no path mismatch between what the bridge thinks the vault is and what Obsidian has open, and no restart dance when you switch vaults. The cost is that the server only exists while Obsidian is running and only on the machine where Obsidian runs. If your AI client is on a different host, this design has nothing to offer you. The intended reader is someone with an MCP-compatible client on the same desktop as their vault, who wants the assistant to read and write notes without maintaining another daemon.
Eight tools, thirteen vault operations, and a permission layer
The README describes eight tools, each acting as a family of operations rather than a single call. The vault tool alone covers thirteen, listed as list, read, create, search, move, split, combine and more. Alongside it the plugin claims first-class Dataview and Bases support and graph traversal across links, tags and backlinks. The permission model is the part worth reading twice. There is a read-only mode, per-operation controls, and path allow and block lists. That matters because an MCP client does not send one request at a time under your supervision; it decides which tools to call while pursuing a task. A read-only mode plus path rules gives you a way to hand an assistant a slice of the vault and have the boundary enforced by the server rather than by the model's judgement. The README does not specify how the allow and block lists interact when a path matches both, or whether the rules apply to graph traversal results as well as direct reads. Treat that as something to confirm against the plugin settings before pointing an agent at a vault you care about.
Getting a client connected: three paths, one port
Installation goes through the Obsidian community plugin directory under the name Semantic Notes Vault MCP, or through BRAT by adding aaronsb/obsidian-mcp-plugin for beta builds. Claude Desktop users get the shortest path: download the .mcpb bundle from the plugin's Settings tab or the latest release, drag it onto the Claude Desktop window, then paste the URL and API key shown in the Settings tab. Claude Code users get a single command, with the ready-made version copied from Settings:
claude mcp add --transport http obsidian http://localhost:3001/mcp --header "Authorization: Bearer YOUR_API_KEY"
Everything else speaks the same HTTP transport through a config entry. The README gives this shape, with one entry per vault if you run several Obsidian instances on different ports:
{ "mcpServers": { "obsidian-vault": { "transport": { "type": "http", "url": "http://localhost:3001/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } }
For multi-vault one-click installs there is a maker script, node scripts/make-mcpb.mjs, which prompts for display name, URL and API key and writes obsidian-mcp-<slug>.mcpb with the fields pre-filled. The default port is 3001 for HTTP and 3443 for HTTPS.
HTTPS trust is the sharp edge, and Bun is why
The HTTPS server uses a self-signed certificate generated on first start and stored at .obsidian/plugins/semantic-vault-mcp/certificates/default.crt inside the vault. MCP clients reject self-signed certificates by default, so the connection fails until you trust it explicitly. The README is unusually direct about the trap here. Claude Code runs on Bun, and Bun does not read the macOS system keychain, so adding the certificate to Keychain Access has no effect on it. The documented fix is NODE_EXTRA_CA_CERTS pointed at the plugin certificate, plus launchctl setenv NODE_EXTRA_CA_CERTS for GUI apps started from the macOS dock. Clients that use the system trust store, such as Claude Desktop and Node with --use-system-ca, can instead take the certificate through the macOS Keychain with security add-trusted-cert. The README also warns against NODE_TLS_REJECT_UNAUTHORIZED=0, since it disables verification for every HTTPS connection the client makes and hides expired or tampered certificates. The certificate is valid for one year and regenerated afterwards, at which point the trust step has to be repeated. That is a recurring maintenance task, not a one-off.
Where this design does not fit
The plugin is the wrong tool when the vault and the client are not on the same machine. There is no documented remote or multi-user mode; the transport is local HTTP with a bearer key, and the certificate is self-signed. It is also wrong for headless or scheduled work. Because the server lives inside Obsidian, nothing answers on port 3001 when Obsidian is closed, so a cron job or a CI step that reads notes cannot use it. Multi-vault setups get awkward in a specific way: the README's answer is one client entry per vault on a distinct port, which means the assistant sees separate servers rather than one view across vaults. Cross-vault search or linking is therefore a client-side problem, not something the plugin solves. Finally, the operations are described at the level of the vault tool family. If your workflow depends on a precise transaction guarantee across several writes, the material here does not state one, and you should not assume it.
How it compares with the filesystem-first approach
The obvious alternative is an MCP server that reads the vault directory directly from disk, with no Obsidian involvement. That approach has real advantages: it runs headless, it works over SSH or in a container, and it does not care whether Obsidian is open. It also loses everything that makes the vault more than a folder of Markdown. Dataview queries, Bases, backlink resolution and the plugin's own index only exist inside Obsidian, so a filesystem server has to reimplement or skip them. Semantic Notes Vault MCP sits on the other side of that trade: it inherits Obsidian's view of the vault, including resolved links and query results, and pays for it with a hard dependency on a running desktop application. Neither is strictly better. If your notes are plain Markdown and your queries are grep, the filesystem server is less machinery. If your vault leans on Dataview or Bases and you want the assistant to see what you see, the in-process server is the only one of the two that can.
Licence, releases and what maintenance looks like
The repository is MIT-licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is a permissive baseline; it says nothing about the Obsidian plugin ecosystem's own distribution terms, and this is not legal advice. On maintenance, the recent release history shows 0.12.6 in August 2026 followed by 0.12.7 and 0.12.8 on the same day in early September 2026, with the last push dated 2026-09-10. Same-day patch pairs usually mean a fix landed and was corrected immediately, which is normal for a project at this version number but also a signal that the API surface is still moving. For an operator, the recurring costs are concrete: re-trust the certificate after each yearly regeneration, re-run the .mcpb maker if you want pre-filled bundles for several vaults, and expect config keys or tool names to shift between minor versions. Pin a version you have verified rather than tracking the latest release, and read the release notes before upgrading.
Editorial conclusion
Adopt it if you already run Obsidian on the same machine as your MCP client and want vault access without a second process. Skip it if you need a headless vault server, remote access, or one client entry that spans several vaults. Verify first that your client's runtime trusts the plugin certificate: check whether .obsidian/plugins/semantic-vault-mcp/certificates/default.crt exists, then set NODE_EXTRA_CA_CERTS for Bun-based clients such as Claude Code rather than disabling TLS verification.
Community notes