Claude Code + Obsidian MCP: Setup Guide (Tested with MCPVault)

Claude Code + Obsidian MCP setup guide

To connect Claude Code to an Obsidian vault over MCP, run claude mcp add obsidian -- npx -y @bitbonsai/mcpvault@latest /path/to/your/vault from the project where you want vault access. MCPVault reads and writes the vault’s Markdown files directly, so Obsidian doesn’t need to be open and no Obsidian plugin is involved. Below are the exact commands, the .mcp.json version for sharing, a real prompt that reads and edits a note through the server, and the problems you’re likely to hit.

Tested on: Claude Code 2.1.326, macOS (Apple Silicon), 17 November 2026. Every command below was run for this guide and the outputs are copied from that run. Drafted with AI assistance (Claude) and checked against the official docs linked in the text.

One thing first: if you start Claude Code inside the vault folder itself, you don’t need MCP, because Claude Code’s own file tools already work there. That setup, and the other ways to connect the two, are in Connect Claude Code to Obsidian: every method, tested. MCP is the answer when Claude Code runs in another folder, such as a code repository, and needs your notes.

Which Obsidian MCP server to use

Figures from GitHub on 17 November 2026:

Server Obsidian must be running Latest release Stars
MCPVault No (reads files) v0.18.4, 14 Nov 2026 1,725
obsidian-mcp No (reads files) v2.0.0, 14 Aug 2026 752
Local REST API with MCP (plugin) Yes 5.5.2, 17 Oct 2026 3,158
mcp-obsidian Yes (needs the Local REST API plugin) PyPI 0.2.3, 20 Aug 2026 4,543

I went with MCPVault for three reasons:

  • No app, no plugin. “Obsidian does not need to be running, and no Obsidian plugin is required” (README). The plugin-based servers need Obsidian open plus an API key.
  • Maintained. Its changelog lists ten versions between 22 October and 14 November 2026, including security fixes (CHANGELOG).
  • Used. The npm registry counted 13,221 downloads in the week to 15 November, against 7,784 for obsidian-mcp-server and 3,988 for obsidian-mcp.

New to MCP servers in Claude Code generally? Start with Claude Code MCP servers.

Before you start

  • Claude Code installed and signed in.
  • Node.js 22.12.0 or later. MCPVault 0.18.0 raised the minimum from Node 20 (CHANGELOG); check with node --version.
  • The absolute path of your vault. cd into the vault and run pwd to get it.
$ claude --version
2.1.326 (Claude Code)
$ node --version
v26.8.2
$ npm view @bitbonsai/mcpvault version engines.node
version = '0.18.4'
engines.node = '>=22.12.0'
$ sw_vers -productVersion && uname -m
26.7.1
arm64

My test setup: a scratch vault with four notes (a project note, an inbox note, a daily note and a resource note) and a separate empty folder standing in for a code project.

Step 1: Pick a scope

Claude Code stores MCP servers at one of three scopes (Claude Code docs: MCP scopes):

Scope Flag Stored in Loads in
Local (default) none, or --scope local ~/.claude.json, under this project’s path This project, only for you
Project --scope project .mcp.json in the project root This project, for everyone who has the file
User --scope user ~/.claude.json Every project on your machine

For a personal vault, local scope in the project that needs it is the cautious choice; user scope if you want the vault in every session. I tested local and project scope only.

Step 2: Add the server

cd ~/code/my-app
claude mcp add obsidian -- npx -y @bitbonsai/mcpvault@latest /Users/you/Documents/Notes
  • obsidian is the server name. Its tools show up as mcp__obsidian__read_note and so on.
  • -- separates Claude Code’s options from the command that starts the server. “Everything after -- is passed to the server untouched” (MCP docs).
  • -y stops npx asking to install the package, and @latest picks up fixes as they ship.
$ cd my-app
$ claude mcp add obsidian -- npx -y @bitbonsai/mcpvault@latest "$SCRATCH/vault"
Added stdio MCP server obsidian with command: npx -y @bitbonsai/mcpvault@latest $SCRATCH/vault to local config
File modified: ~/.claude.json [project: $SCRATCH/my-app]

The same server at user scope, for every project, is claude mcp add obsidian --scope user -- npx -y @bitbonsai/mcpvault@latest /Users/you/Documents/Notes (MCP docs).

Step 3: Check that it connected

claude mcp list
claude mcp get obsidian

claude mcp list health-checks each server and prints a status such as ✔ Connected, ✘ Failed to connect or, for an unapproved .mcp.json server, ⏸ Pending approval (MCP quickstart). I timed two runs back to back, since the first one has to let npx fetch the package:

$ time claude mcp list
Checking MCP server health…
obsidian: npx -y @bitbonsai/mcpvault@latest $SCRATCH/vault - ✔ Connected
real 8.95

$ time claude mcp list
Checking MCP server health…
obsidian: npx -y @bitbonsai/mcpvault@latest $SCRATCH/vault - ✔ Connected
real 8.32

About 9 seconds both times, because the package was already in my npx cache. On a machine that has never run MCPVault, expect the first check to take longer while npx downloads it.

claude mcp get shows the scope, the status and the exact command Claude Code will run:

$ claude mcp get obsidian
obsidian:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: npx
  Args: -y @bitbonsai/mcpvault@latest $SCRATCH/vault
  Environment:

To remove this server, run: claude mcp remove obsidian -s local

Inside an interactive session, /mcp shows the same server with its tool count (MCP docs).

Step 4: Use it

Ask in plain language and name the server if you want to be sure Claude uses it. For a script, pre-approve the server’s tools with mcp__obsidian__*, the documented pattern for every tool on one server (permissions docs). Without an allow rule, a claude -p run denies calls that need approval (headless docs).

claude -p "Use the obsidian MCP tools to list the top-level folders of my vault, read Projects/Website Relaunch.md, and add the task '- [ ] Send the final page list to the design agency' as the last item under its '## Milestones' heading without changing anything else. Then list the MCP tools you used." \
  --allowedTools "mcp__obsidian__*"

The tools Claude called, its answer, and the note afterwards:

## tool calls
ToolSearch                     select:mcp__obsidian__list_directory,read_note,patch_note,write_note,get_note_outline
mcp__obsidian__list_directory  {"path":"/"}
mcp__obsidian__read_note       {"path":"Projects/Website Relaunch.md"}
mcp__obsidian__patch_note      {"path":"Projects/Website Relaunch.md","oldString":"- [ ] Launch\n","newString":"- [ ] Launch\n- [ ] Send the final page list to the design agency\n"}
mcp__obsidian__read_note       {"path":"Projects/Website Relaunch.md"}
## result
I added the task as the last item under `## Milestones`. When I read the note again
afterwards, everything else was unchanged, including the frontmatter.
Top-level folders in your vault: Daily, Inbox, Projects, Resources.
The new task now comes after "Launch", but the note says the agency started work on
16 November, which was yesterday. You may want to move it up near "Design mockups".
turns: 6  cost_usd: 0.35  duration: 15 s

$ cat "Projects/Website Relaunch.md"   (Milestones section)
## Milestones
- [x] Content audit
- [ ] Navigation draft
- [ ] Design mockups (agency starts 16 November)
- [ ] CMS migration
- [ ] Launch
- [ ] Send the final page list to the design agency

Two things I liked: it used patch_note (a targeted find-and-replace) instead of rewriting the whole note, and it re-read the note afterwards to check nothing else changed. The frontmatter was untouched.

MCPVault exposes 18 tools (README):

  • Files: read_note, write_note (overwrite, append or prepend), patch_note, delete_note, move_note, move_file
  • Partial reads: get_note_outline, read_note_lines
  • Folders and batches: list_directory, read_multiple_notes
  • Search: search_notes, with BM25 ranking
  • Metadata: get_frontmatter, update_frontmatter, get_notes_info, get_vault_stats, manage_tags, list_all_tags
  • Links: wiki_link, which resolves a note name to its path

Share it with .mcp.json

Project scope writes the server into .mcp.json at the project root, which you can commit (MCP docs):

claude mcp add obsidian --scope project -- npx -y @bitbonsai/mcpvault@latest /Users/you/Documents/Notes
$ claude mcp add --scope project obsidian -- npx -y @bitbonsai/mcpvault@latest "$SCRATCH/vault"
Added stdio MCP server obsidian with command: npx -y @bitbonsai/mcpvault@latest $SCRATCH/vault to project config
File modified: $SCRATCH/my-app/.mcp.json

$ cat .mcp.json
{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bitbonsai/mcpvault@latest",
        "$SCRATCH/vault"
      ],
      "env": {}
    }
  }
}

$ claude mcp list
Checking MCP server health…
obsidian: npx -y @bitbonsai/mcpvault@latest $SCRATCH/vault - ⏸ Pending approval (run `claude` to approve)

Two things to know. First, Claude Code asks you to approve .mcp.json servers in an interactive session before it uses them; until then claude mcp list shows them as pending. Print-mode (claude -p) runs can’t show that prompt and load them without asking (MCP docs).

Second, a hard-coded vault path only works on your machine. .mcp.json supports ${VAR} and ${VAR:-default} in command, args, env, url and headers (MCP docs), so each person can point it at their own vault. I also added MCPVault’s --read-only flag. Per the README, “Mutating tools are omitted from discovery and rejected if called directly” (README):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@bitbonsai/mcpvault@latest", "${OBSIDIAN_VAULT}", "--read-only"]
    }
  }
}

Then I set OBSIDIAN_VAULT, asked Claude to list the server’s tools, and told it to write to a note anyway:

$ export OBSIDIAN_VAULT="$SCRATCH/vault"
$ claude mcp list
obsidian: npx -y @bitbonsai/mcpvault@latest ${OBSIDIAN_VAULT} --read-only - ⏸ Pending approval (run `claude` to approve)
$ shasum "Inbox/Newsletter Ideas.md"
3147e659ec4bb3514da12c71c7074091a3b75427

$ claude -p "Using the obsidian MCP server: first list the names of the tools it gives you, then try to append the line '- test' to Inbox/Newsletter Ideas.md, and report exactly what happened." --allowedTools "mcp__obsidian__*"
## tool calls
ToolSearch                      +obsidian append write note
mcp__obsidian__get_notes_info   {"paths":["Inbox/Newsletter Ideas.md"]}
## result
I couldn't append the line, because the obsidian MCP server has no tool that writes to notes.
Nothing was changed. What the server provides (11 tools, all read-only):
read_note, read_note_lines, read_multiple_notes, get_note_outline, get_notes_info,
get_frontmatter, search_notes, list_directory, wiki_link, get_vault_stats, list_all_tags
turns: 3  cost_usd: 0.32

$ shasum "Inbox/Newsletter Ideas.md"
3147e659ec4bb3514da12c71c7074091a3b75427

Three things this run showed. The list prints ${OBSIDIAN_VAULT} unexpanded, but the variable is expanded when the server starts. The print-mode run used the .mcp.json server even though claude mcp list still said “Pending approval”. And with --read-only the server only exposed its 11 read tools, so the note’s checksum is identical before and after. Claude also didn’t try to sneak around it with a shell command, because I’d asked for the MCP server specifically.

Safety settings worth adding

  • Deletes are permanent by default. delete_note uses trashMode: "none" unless the call asks for local (the vault’s .trash) or system (README). It does require the path twice as confirmation. To rule it out, add "mcp__obsidian__delete_note" to permissions.deny in .claude/settings.json (permissions docs).
  • Dotfiles are off limits. MCPVault blocks .obsidian, .git, other dotfiles, symlink escapes and path traversal (README).
  • Big results are capped. Claude Code warns when an MCP tool returns more than 10,000 tokens and cuts off at 25,000 by default; raise the cap with MAX_MCP_OUTPUT_TOKENS (env vars docs).

Troubleshooting

Pending approval in claude mcp list

That’s a project-scoped server from .mcp.json you haven’t approved yet. Run claude in that folder and approve it, or add the server at local scope instead (MCP docs: server status). To reset earlier approval choices, run claude mcp reset-project-choices.

Failed to connect

Run the server command yourself to see its error: npx -y @bitbonsai/mcpvault@latest /Users/you/Documents/Notes. A working stdio server just sits waiting for input; press Ctrl+C. The usual culprit is Node.js older than 22.12.0. claude mcp get obsidian also prints the failure detail on an Issue: line (MCP docs).

The command breaks when you copy it from the README

MCPVault’s README gives the Claude Code one-liner without -- (README). Anthropic’s docs say Claude Code would then try to parse the server’s flags as its own (MCP docs). Here is what happened when I tried it with -y and --read-only:

$ claude mcp add obsidian npx -y @bitbonsai/mcpvault@latest "$SCRATCH/vault" --read-only
error: unknown option '-y'

Nothing was added: Claude Code read -y as one of its own flags and stopped. Put -- before npx and everything after it is passed to the server untouched.

Slow first start

The first launch downloads the package through npx. Claude Code waits 30 seconds for an MCP server to start by default; set MCP_TIMEOUT in milliseconds to wait longer, for example MCP_TIMEOUT=60000 claude (env vars docs).

“File not found” for a note that exists

The server is probably using the wrong vault root: with no path, MCPVault uses the current working directory (README). Always pass an absolute path. Versions before 0.18.4 also mishandled absolute paths when the vault sat under a symlink (CHANGELOG), which is another reason to keep @latest.

Remove the server

claude mcp remove obsidian                    # local scope
claude mcp remove obsidian --scope project    # .mcp.json
$ claude mcp remove obsidian
Removed MCP server "obsidian" from local config
File modified: ~/.claude.json [project: $SCRATCH/my-app]
$ claude mcp list
Checking MCP server health…
$ claude mcp remove obsidian --scope project
Removed MCP server obsidian from project config
File modified: $SCRATCH/my-app/.mcp.json
$ cat .mcp.json
{
  "mcpServers": {}
}

Alternative: Local REST API with MCP

If you need Obsidian’s own features, such as running commands or acting on the note that’s open, the Local REST API plugin has served a built-in MCP endpoint since version 4.0.0 (release notes). With the plugin installed and its API key copied, the README’s command is:

claude mcp add --transport http obsidian-app https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

Obsidian has to be running, and the plugin needs Obsidian 1.13.1 or later since version 5.1.0 (releases). I didn’t test this route for this guide.

FAQ

Does Obsidian need to be open for the Obsidian MCP server to work?

Not with MCPVault or obsidian-mcp, which read the files directly. Servers that use the Local REST API plugin need Obsidian running.

Can I connect more than one vault?

Yes. Add one server per vault with different names, such as obsidian-work and obsidian-personal; MCPVault’s README shows the same pattern for Claude Desktop (README).

Does the same server work in Claude Desktop?

Yes. The README gives a claude_desktop_config.json entry with the same npx command and vault path (README).

Is MCPVault free?

Yes, it’s MIT-licensed open source (GitHub). Claude Code itself needs a Claude subscription, a Console account or a supported cloud provider (quickstart).

Sources

Similar Posts