Semantic Notes Vault MCP: an Obsidian MCP server that runs inside the plugin

The problem: getting an AI client into a local Obsidian vault

Obsidian stores notes as plain files in a folder, which makes it easy to read and hard to expose safely. The usual workaround is a bridge: run a separate Node process or a REST-API plugin, point it at the vault path, and let the AI client call that. The bridge then has to duplicate Obsidian's own understanding of links, tags, backlinks, Dataview queries and Bases, and it drifts whenever Obsidian changes. The README frames the alternative directly: the server is the plugin, with no external process to launch and no separate REST-API plugin in between.

That matters most for people who already keep their working knowledge in Obsidian and want an assistant to operate on it in place. The plugin exposes 8 tools, and the README is explicit that each tool is a family rather than a single call: the vault tool alone handles 13 operations including list, read, create, search, move, split and combine. The intended audience is the Obsidian user who wants Claude Desktop, Claude Code, Cline or Continue.dev to read, write, search and traverse the vault, not someone looking for a general document store.

How the in-plugin MCP server is put together

The architecture is the unusual part. The MCP server is compiled into the plugin bundle that Obsidian loads, and it listens over HTTP on localhost. Claude Code is registered against http://localhost:3001/mcp with a bearer token in an Authorization header; the HTTPS variant runs on https://localhost:3443/mcp. The package.json confirms the shape of this: express, cors and @modelcontextprotocol/sdk are runtime dependencies, and the plugin is built with esbuild into main.js, the entry point Obsidian expects.

Because the server lives inside Obsidian, it inherits the app's view of the vault. Dataview and Bases support are described as first-class, and graph traversal runs across links, tags and backlinks. A separate process pointed at a folder would have to reimplement all of that. The trade-off is coupling: the MCP endpoint is only reachable while Obsidian is running, and its lifetime is the plugin's lifetime. There is also a certificate lifecycle to manage, since the HTTPS server generates a self-signed certificate on first start and stores it at .obsidian/plugins/semantic-vault-mcp/certificates/default.crt inside the vault, valid for one year.

The permission model sits in the plugin rather than the client. The README lists a read-only mode, per-operation controls, and path allow and block lists, with the stated goal that the AI only does what you allowed. That is the right place for the control, because the client cannot be trusted to police itself, but it does mean the effective safety of the setup depends on the configuration you set in the Settings tab.

Installing the plugin and connecting Claude Code over HTTP

The primary path is the Obsidian Community Plugin directory: open Settings, go to Community plugins, choose Browse, search for "Semantic Notes Vault MCP", then install and enable it. The README also documents BRAT as a beta channel, added as `aaronsb/obsidian-mcp-plugin`.

For Claude Desktop, the recommended route is the .mcpb bundle, downloaded from the plugin's Settings tab or the latest release, then dragged onto the Claude Desktop window or double-clicked. Claude Desktop opens an install dialog with two fields, and you paste the URL and API key shown in the plugin's Settings tab. The README notes that double-click behaviour varies by platform and suggests dragging the file onto the window if the association does not fire.

For Claude Code, the README gives a single command. Copy the ready-made version with your key from the Settings tab, or adapt this form:

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

Running it should register the server in Claude Code under the name obsidian, pointing at the local MCP endpoint with your key in the Authorization header. For HTTPS, the README says to use https://localhost:3443/mcp instead, which brings in the certificate step described below.

Adding the server to Cline, Continue or a custom client

Clients that read an MCP config file instead of taking a command need an entry per vault, which is also how multi-vault setups are handled: one entry per Obsidian instance, each on its own port. The README gives this JSON shape, with the transport type set to http and the bearer token in the headers block.

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

After saving the config and restarting the client, the obsidian-vault entry should appear in its list of MCP servers. If you want one-click installs per vault rather than pasting fields, the repository ships a maker script. It prompts for a display name, URL and API key, and writes a pre-filled bundle you can drop into Claude Desktop.

node scripts/make-mcpb.mjs

The script outputs obsidian-mcp-<slug>.mcpb with the values pre-filled, so installing it needs no typed fields.

The HTTPS certificate is the part that actually breaks

Over HTTPS the plugin uses a self-signed certificate, and MCP clients reject those by default. The README is unusually direct about the failure mode: Bun does not consult the macOS system keychain for TLS trust, so trusting the certificate in Keychain Access has no effect for Claude Code, which runs on Bun. That is described as almost always the real reason an HTTPS connection from Claude Code fails. The fix is to point NODE_EXTRA_CA_CERTS at the plugin's certificate:

export NODE_EXTRA_CA_CERTS=/path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt

For GUI apps launched from the macOS dock, the README adds a launchctl setenv call with the same path so the variable reaches Claude Code. Both need re-running when the certificate is regenerated, for example after the one-year validity expires.

The README also warns against NODE_TLS_REJECT_UNAUTHORIZED=0, because it disables verification for every HTTPS connection the client makes, not just this one, and hides expired, revoked or tampered certificates. That is the correct call, and it is worth repeating: the convenient workaround is the one that quietly weakens every other connection your client opens. If you only need this working today, the plain HTTP endpoint on port 3001 avoids the certificate problem entirely, at the cost of unencrypted local traffic.

Where this is the wrong tool

The server only exists while Obsidian is open. If your workflow needs a headless vault endpoint for a CI job, a scheduled script or a server-side agent, this is the wrong architecture: the plugin is loaded by a desktop app, and closing the app closes the endpoint. A standalone server process pointed at the vault folder is the better fit there, even though it gives up Obsidian's native view of Dataview, Bases and backlinks.

The second limit is installation. Everything routes through Obsidian's community plugin system or BRAT. If your organisation restricts community plugins, or you run Obsidian in an environment where you cannot enable them, none of the onboarding paths apply. There is no documented standalone binary, and the README does not describe a way to run the MCP server without the plugin.

The third is that the security posture is configuration, not architecture. Read-only mode, per-operation controls and path allow and block lists are all settings you have to set correctly. The README does not document what the defaults are, nor does it document rollback behaviour if an AI writes something you did not want. Before pointing a client at a vault you care about, confirm in the Settings tab which operations are enabled and whether a write is actually rejected.

How it differs from a standalone Obsidian MCP server

The obvious alternative is a separate MCP server that reads the vault directory from outside Obsidian, typically paired with the community REST-API plugin. The difference is not packaging, it is what the server can see. An external process gets files and whatever metadata it parses itself. The in-plugin server runs inside the app that already resolves links, tags, backlinks, Dataview queries and Bases, so those features are available to the AI without reimplementation, and the README treats Dataview and Bases support as first-class rather than best-effort.

The cost runs the other way. An external server can run as a service, restart independently, and keep serving when Obsidian is closed. It also does not need a self-signed certificate generated inside a vault folder, and it does not depend on a desktop app being open for the endpoint to answer. If your assistant needs the vault available on a schedule, the external design wins; if it needs the vault understood the way Obsidian understands it, this plugin is the shorter path.

Maintenance, licence and what a version bump costs

The repository is MIT licensed, which permits commercial and private use and modification with the licence text retained; that is a statement about the licence, not legal advice, and organisations with policy constraints should have their own review. The last push was on 2026-09-10, and the most recent release listed is 0.12.8 on 2026-09-03, so the project is not archived and the release cadence over the past weeks is visible in the release list.

Upgrade cost is mostly client-side. The plugin is built with esbuild, and the Makefile exposes a check target that runs build, lint and a coverage gate, so the maintainer's own quality path is scripted rather than manual. For users, the friction is the certificate: the README says to re-run the trust commands whenever the plugin regenerates its certificate, including after the one-year validity expires. Version bumps also mean the .mcpb bundle changes, so a Claude Desktop install pinned to an older bundle will not pick up new tools until you install the new one. Budget for that, and for re-checking your permission settings after a major upgrade, since the README does not promise that configuration survives every release.

Editorial conclusion

Adopt it if you already live in Obsidian and want an MCP client to read and write notes through the plugin you already run, with a read-only mode and path allow/block lists as the safety layer. Do not adopt it if you cannot install a community plugin, or if you need a server that outlives Obsidian itself, because the server only exists while the app is open. Before trusting it with a real vault, verify three things on your own machine: that the plugin's Settings tab shows the URL and API key your client is using, that a read-only configuration actually blocks a write attempt, and that your client runtime trusts the self-signed certificate (Bun-based clients need NODE_EXTRA_CA_CERTS, not the macOS keychain).

Frequently asked questions

Official sources

1. aaronsb/obsidian-mcp-plugin on GitHub
2. Issues
3. License: MIT
4. README
5. Releases