If you’ve already got Claude Code reading and
writing files in your Obsidian vault,
you’ve solved the basic integration. But there’s a second layer worth
unlocking: an Obsidian MCP server that gives Claude Code first-class
access to vault-specific operations like backlinks, tags, daily notes,
and graph-aware search.
This guide walks through the full setup — picking a server,
installing it, wiring it into Claude Code, verifying the connection, and
using it for the workflows that file-level access can’t deliver. If
you’re looking for the broader integration first, start with our Claude Code +
Obsidian guide and come back here when you’re ready to go
deeper.
What an
Obsidian MCP Server Adds Beyond File Access
When Claude Code reads files directly from your vault, it sees
markdown the way any program would: a folder tree of .md
files. That’s enough for summarization, drafting, and find-and-replace.
What it misses is everything Obsidian builds on top of those files — the
relationships between notes, the tag graph, the daily-note convention,
the way frontmatter is interpreted.
An MCP server closes
that gap. MCP (Model Context Protocol) is the open standard Anthropic
released for letting AI agents call external tools. An Obsidian MCP
server is a small program that runs alongside Claude Code, exposes
Obsidian-aware operations, and lets Claude call them like any other
tool.
Concretely, an MCP server can give Claude Code:
- Backlink lookups — “show me every note that links
to this one” - Tag-aware queries — “find all notes with both
#researchand#ai” - Daily-note routing — “open today’s daily note”
without the agent guessing the date format - Vault-wide search with proper ranking — better than
grep, especially for fuzzy matches - Graph operations — finding orphan notes, mapping
topic clusters, detecting duplicates - Frontmatter awareness — querying or updating YAML
metadata cleanly
If your vault is small and you mostly read and write notes one at a
time, you don’t need this. If your vault is the central nervous system
of your work and Claude Code is going to operate on it at scale, you
do.
Picking the Right
Obsidian MCP Server
There’s no single official Obsidian MCP server. Several open-source
community projects exist, each with different tradeoffs. Search GitHub
for “obsidian mcp server” and you’ll find current options. When
evaluating, look at four things:
1. Recent activity. MCP is moving fast. A server
that hasn’t been updated in six months is probably out of step with the
current Claude Code MCP spec. Check the most recent commit date.
2. Feature coverage. Some servers expose only basic
file operations (which you already have). The valuable ones expose
backlinks, tags, daily notes, and search. Read the README and look at
the list of tools the server registers.
3. Implementation language. Most are Node.js, some
are Python, a few are Go or Rust. Pick one that matches your existing
toolchain so you’re not installing a new runtime just for this.
4. Security posture. This server will have read and
(often) write access to your entire vault. Prefer servers that: – Are
open source and auditable – Run locally — never require sending vault
contents to a third-party endpoint – Let you scope access to specific
folders if you have sensitive notes
Once you’ve picked one, the setup pattern is roughly the same across
all of them. We’ll use a generic flow — your chosen server’s README will
fill in the specifics.
Installing and Running the
Server
Step 1 — Install the runtime. For most Obsidian MCP
servers, that means Node.js. Install it via nodejs.org or your package manager.
Confirm with:
node --versionStep 2 — Install the MCP server. Most projects
publish to npm or distribute via git clone. A typical
install looks like:
npm install -g obsidian-mcp-serverOr, for a clone-based install:
git clone <repo-url>
cd <repo-folder>
npm installStep 3 — Configure the server. Every Obsidian MCP
server needs to know where your vault lives. This is usually a
command-line argument or a config file:
obsidian-mcp-server --vault ~/Documents/MyVaultIf the server supports a config file, prefer that — it’s easier to
reproduce across machines and check into a private dotfiles repo.
Step 4 — Test the server in isolation first. Before
connecting it to Claude Code, run the server directly and watch the
output. You should see logs indicating it loaded your vault, found your
notes, and is listening on a port or stdio. If it crashes here, fix it
now — debugging is much harder once Claude Code is in the loop.
Connecting the MCP
Server to Claude Code
Claude Code reads MCP server configuration from a JSON file. The
exact location depends on your setup — there’s a global config in your
home directory (~/.claude/settings.json or similar) and a
project-scoped config (.claude/settings.json in the project
folder). The pattern is the same in both.
Add an entry under mcpServers:
{
"mcpServers": {
"obsidian": {
"command": "obsidian-mcp-server",
"args": ["--vault", "/Users/you/Documents/MyVault"]
}
}
}A few notes:
- Use absolute paths. Relative paths like
~/Documents/MyVaultmay not resolve correctly when Claude
Code spawns the server. - Quote paths with spaces. If your vault path has
spaces, escape them or quote them properly inside the JSON. - One server, one entry. If you run multiple MCP
servers (Obsidian, GitHub, etc.), each gets its own key under
mcpServers.
Save the config and restart Claude Code. The next session should pick
up the new server.
Verifying
the Connection (and What to Do When It Doesn’t Work)
Once Claude Code is running, type /mcp inside the
session. You should see the Obsidian server listed and the tools it
exposes. If you see it: the connection is good — try a real query, like
“list all backlinks to my note titled ‘Q2 Strategy.’”
If /mcp doesn’t show your server, work through this
checklist:
- Did Claude Code parse the config? Check the Claude
Code logs (location varies by platform — your README will say). Look for
MCP config errors. - Is the command on your PATH? If
commandisobsidian-mcp-server, make sure that
binary is reachable. Try the absolute path to the binary instead. - Does the server crash on startup? Run the same
command Claude Code is running, manually, in a terminal. If it crashes
outside Claude Code, the bug is in the server config, not the
integration. - Vault path correct? A typo in the vault path is the
most common silent failure. The server may start cleanly but expose zero
useful tools. - Permission issues? On macOS especially, the vault
folder may need explicit Full Disk Access for the terminal app or for
Node itself.
Once /mcp shows the server connected, the integration is
done.
Real Workflows the MCP
Server Unlocks
Here’s the part worth the setup. With the Obsidian MCP server
connected, Claude Code can do things it couldn’t with raw file access
alone:
- “Find every orphan note in my vault.” With backlink
awareness, this is a single tool call. Without it, Claude Code would
have to walk the entire vault manually. - “Show me every note that mentions Project X but isn’t tagged
#project-x.” This requires both content search and
tag-aware filtering — exactly what an MCP server provides. - “Open today’s daily note and append a meeting
summary.” Daily-note routing knows your date format and folder
convention. - “Find duplicate notes — anything with overlapping titles or
near-identical content.” Vault-wide ranked search makes this
practical. - “Re-tag every note in
/Inbox/based on its
content and move it to the right folder.” A multi-step workflow
that combines reading, classifying, and writing — exactly what agents
are good at when they have the right tools.
For more day-to-day patterns once your MCP server is live, see our daily
workflows for Claude Code + Obsidian power users. For the broader
workflow philosophy — taking raw notes through to shipped work — see our
Claude
Code markdown workflow guide.
Frequently Asked Questions
Is there an official Obsidian MCP server from Obsidian or
Anthropic? Not at the time of writing. The available servers
are open-source community projects. Check GitHub for current options and
pick one that’s actively maintained.
Do I need an MCP server to use Claude Code with
Obsidian? No. Claude Code can read and write your vault as
plain markdown files without any MCP server. Add the MCP server when you
want graph-aware operations (backlinks, tags, ranked search) that file
access alone can’t provide.
Will the MCP server slow down Claude Code? The
startup cost is small (a few hundred milliseconds when Claude Code
spawns the server). Per-call latency depends on the operation, but for
typical vault sizes it’s imperceptible. If you have a vault with tens of
thousands of notes, profile your specific server.
Can I run multiple MCP servers at once? Yes. Claude
Code supports any number of MCP servers configured in parallel. Many
users run an Obsidian server alongside a GitHub server, a database
server, or a custom in-house server.
Is my vault data sent anywhere when using an MCP
server? The MCP server itself runs locally on your machine.
Vault contents are read from disk and passed to Claude only when Claude
Code chooses to call a tool — same pattern as raw file access. The
server should never need to send your vault to a third-party endpoint;
if it does, pick a different server.
What if the MCP spec changes and breaks my server?
MCP is stabilizing but still evolving. Pin the server version in your
config and update deliberately. Watch the maintainer’s release notes for
breaking changes.
Where to Go From Here
Setting up the Obsidian MCP server is the bridge between “Claude Code
can read my notes” and “Claude Code can operate on my notes the way I
do.” Once it’s wired up, the workflows that felt clunky with raw file
access become single-prompt operations.
If you want to step back and see how this fits into the broader
integration, start with our Claude Code +
Obsidian pillar guide. If you’d like help designing an end-to-end AI
knowledge system around this stack, let’s design
your system.