How to Connect Claude Desktop to Obsidian — A Journey Through 4 MCP Servers

Imagine: you have 400+ notes in Obsidian, accumulated over years. Everything is scattered across the vault root, concepts mixed with technical notes, there are duplicates (ideas.md and an ideas/ folder with 13 files inside), no system. You want to bring order — build a proper folder architecture, add MOC files, organize tags. Doing it manually is tedious and slow. The logical thought: connect Claude to Obsidian via MCP, let AI do the refactoring. Turns out — it's a path through a minefield. Here's what I had to go through to reach a working solution.

What is MCP and Why It's Not So Simple

MCP (Model Context Protocol) is an open protocol from Anthropic that allows Claude to connect to external tools and data. The principle is simple: a local server runs, exposing "tools", and Claude calls them during conversation.

For Obsidian there are theoretically plenty of MCP servers. In practice — each has its own problems.

The main problem of the Obsidian ecosystem: Obsidian is a closed application without an official MCP. The community filled the gap, but each implementation goes its own way, and none has "official blessing".

Attempt 1: MarkusPfundstein/mcp-obsidian

The first tool found when searching. 3,400 stars on GitHub, featured in every tutorial. Seems like a safe choice.

How it works: Python server based on the Local REST API plugin in Obsidian. The server communicates with the plugin via HTTPS, the plugin performs operations through the Obsidian API.

What Went Wrong

• Not updated in 17 months
• 85 open issues
• No move/rename — only read, write, append, delete
• Local REST API has a documented data-loss bug: POST endpoint can silently overwrite a file on append

Not suitable for refactoring — we need to move files and preserve links. Moving on.

Attempt 2: aaronsb/obsidian-mcp-plugin

Found an option that works as a native Obsidian plugin. This means direct access to Obsidian's internal API — backlinks, Dataview, link graph. Move via the native API updates all wiki-links automatically, because Obsidian handles this itself.

Setup Difficulties

• Plugin is not in the official Obsidian catalog (PR pending with validation errors)
• Must install via BRAT (Beta Reviewers Auto-update Tool)
• Claude Desktop doesn't accept Bearer token directly through UI — forced enabling HTTPS in the plugin
• Self-signed certificate for localhost creates trust issues

Through all these workarounds I finally connected it. Basic test — vault.move does rewrite [[wikilinks]], works as expected.

What Went Wrong in Production

When I started mass refactoring (drag-and-drop of dozens of folders in Obsidian + simultaneous MCP operations), the server hung for 4+ minutes. Why: the plugin runs inside Obsidian. When Obsidian re-indexes thousands of files after a mass structure change, the plugin blocks along with it.

Conclusion: dependency on an open Obsidian instance and its index is fatal for bulk operations.

Attempt 3: @bitbonsai/mcpvault

Logically — we need a server that doesn't depend on Obsidian. Works directly with files on disk. @bitbonsai/mcpvault — recommended in many reviews. Direct filesystem access, simple setup (npx @bitbonsai/mcpvault@latest /path/to/vault), 14 tools. Obsidian doesn't even need to be running.

Before installing, I checked one critical thing — whether wiki-links update on move. Found a user review:

Filesystem connector doesn't know it's in Obsidian — it sees a folder of <code>.md</code> files and that's it. Doesn't know that filenames carry semantic weight, that every <code>[[wikilink]]</code> will break the moment you rename or move. Auto-update links only works when the rename happens from inside the app. I learned this after asking Claude to clean up file names and came back to a dashboard with half the links broken.

Confirmed in mcpvault's own documentation: PR #101 (wiki link resolution) is in review, not merged. So moving via mcpvault would break half the vault. Not suitable.

Attempt 4: VaultForge (Final)

blacksmithers/vaultforge — specifically built for AI agents that do refactoring.

Architecturally Correct

• Direct filesystem — doesn't depend on Obsidian
• Own wikilink engine — implements [[wikilink]] resolution logic that updates all forms (stem, full path, alias, embed)
• Dry run by default on all destructive operations — first shows what will change, then you confirm
• 27 tools vs 8–14 in competitors: batch_rename, update_links, backlinks (impact analysis), prune_empty_dirs, frontmatter, smart_search (BM25), vault_themes (TF-IDF clustering)
• MIT license, TypeScript, zero sub-dependencies
• 30-second install via .mcpb (one-click extension for Claude Desktop)

Safety Test on Isolated Files

Created 4 test files with cross-links — stem links, links with aliases, links with full paths. Moving one file to a subfolder:

delta.md → subfolder/delta-renamed.md

VaultForge showed a dry run: "1 file will be renamed, 3 links will be updated". Executed for real.

Checked after — all three link types updated correctly. This is exactly what all previous tools were missing.

How to Install VaultForge — Final Instructions

If you have macOS and Claude Desktop:

Step 1

Download the .mcpb file:

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb \
  -o /tmp/vaultforge.mcpb && open /tmp/vaultforge.mcpb

Step 2

Claude Desktop will open the extension install dialog. Enter the absolute path to your vault — no backslashes, normal spaces:

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault

Step 3

Click Save. Claude Desktop will add the extension to config automatically. No restart needed — .mcpb extensions are picked up automatically.

Step 4

Verify: in a new chat ask: "What is the status of my Obsidian vault?" — should return something like totalFiles: 416, totalDirs: 135, ...

What I Learned About the Obsidian MCP Ecosystem

First, "most popular" doesn't mean "working". MarkusPfundstein/mcp-obsidian has 3,400 stars and is the default recommendation, but it's outdated and missing key operations.

Second, a native plugin has a hidden cost. The aaronsb plugin looked ideal — graph, Dataview, native move. But dependency on a running Obsidian instance and its index makes it unsuitable for serious bulk operations.

Third, direct filesystem without a link-engine is a trap. Mcpvault is fast and simple, but "just moving files" destroys vault structure. Links carry imposed semantics that the filesystem doesn't know about. Without its own wikilink logic implementation, the tool becomes a landmine.

Fourth, test on isolated data. Before trusting any tool with mass refactoring — create a test folder with 4–5 files with cross-links and see what happens. 5 minutes of testing saves hours of recovery from backup.

Fifth, keep a git backup of your vault. The most important of all. A single git init inside the vault and periodic commits — that's insurance against any mistakes by an AI agent or tool. If something breaks — git reset --hard brings everything back.

Conclusion

The journey took several hours and three failed attempts. The final architecture looks like this:

• VaultForge — the main working tool. Direct filesystem + own wikilink engine + 27 tools = stable refactoring at any scale.
• Git — vault versioning. Free rollback for any mistake.

Now I can do what this was all started for: ask Claude to organize 400 notes into a proper PARA architecture, merge duplicates, add frontmatter, build MOC maps. Every operation is safe, links are preserved, dry run shows what will happen before anything changes.

If you're also looking at your cluttered Obsidian and want an AI assistant — start with VaultForge right away. Don't repeat my route through dead projects, beta plugins, and filesystem servers without link logic.