obsidian-ai-mcp is an MCP server that gives Claude Code and GitHub Copilot direct access to your vault — search, read, write, and manage notes using natural language. Your files stay local, always.
Obsidian is a free, local-first note-taking app built around plain Markdown files. Think of it as a personal knowledge base that lives on your machine — no cloud sync required, no vendor lock-in.
Obsidian lets you build a personal knowledge base of notes, specs, decisions, and logs — all as plain .md files on disk. You connect ideas with [[wikilinks]], and Obsidian renders them as a graph: a visual map of how your notes relate to each other.
The graph view makes it possible to see, for example, that your auth spec, a debugging session devlog, and a team decision all point to the same architectural note — connections you might not have noticed otherwise.
Because notes are just files, they work with git, grep, any text editor — and now, with AI tools like Claude.
If you spend your day in Claude — debugging, researching, reviewing code, planning — you know this problem.
You ask Claude a question, get a great answer, and move on. Later you can't find it. You write notes after the fact, if at all. Decisions get buried in chat history. Learnings from a debugging session vanish. You copy-paste snippets into a scratch file that never gets organised.
The knowledge is there — it just doesn't go anywhere useful.
With obsidian-ai-mcp, your vault stays in sync with your work. As you're doing something in Claude, just say "log this" or "create a devlog" and it captures it — structured, dated, linked to your other notes. At the end of a session, ask Claude to summarise and promote it to your permanent notes.
No copy-pasting. No context switching. Your vault grows from your work, not from extra effort.
This only works if the notes stay useful. The design intentionally prevents the common failure mode of notes becoming an unreadable wall of AI output:
Notes reflect what's true now, not a log of every change. Outdated content gets replaced or promoted away.
Templates are structured and minimal. Every field exists because it adds signal. Nothing is appended just because it can be.
All AI-generated notes land in Inbox first. You review and promote — permanent notes are never silently overwritten.
A note should answer a question when you come back to it. Open questions are explicit. Next steps are always at the bottom.
There are many ways to give an AI access to a note vault. Most just expose the file system. This one makes three opinionated choices — borrowed from ideas that have worked for personal knowledge management for decades.
Everything AI-generated lands in Inbox/ first — never silently inserted into your permanent notes. You review and promote what's worth keeping. The promote_note tool is append-only by design: it will never overwrite an existing note in Notes/, only add to it.
This mirrors the capture-before-organise principle that David Allen described in Getting Things Done: closing the loop on a thought costs almost nothing if the capture step is frictionless — the friction should live at the curation step, not the capture step.
The two-phase Inbox → Notes flow is a hard constraint, not a preference you can accidentally override.
Notes live in two folders: Inbox/ and Notes/. No nested hierarchies to maintain, no taxonomy decisions to make mid-session.
Niklas Luhmann's Zettelkasten — the note system behind decades of his prolific academic output — worked as a flat collection linked by cross-references, not a filing cabinet. Andy Matuschak's research on evergreen notes reaches the same conclusion: hierarchical organisation tends to bury notes rather than surface them. Links and search do that job better.
You can rename the folders or add subfolders — but the default is deliberately two levels and nothing more.
Drop a vault_context.md in your vault root. The server reads it once at startup and sends it to Claude as part of the session handshake — zero per-call overhead. Claude knows your timezone, your team, your writing style, your recurring projects, every session.
Recent research on persistent AI memory (Mem0, 2025) found that giving a model stable user context increased task accuracy by 26% and reduced token usage by 90% compared to re-stating context each time. vault_context.md is that stable context — plain text you can read and edit.
No prompting rituals. No re-explaining yourself at the start of every session.
The MCP server runs locally on your machine and reads your vault as plain files — no Obsidian app needs to be open.
Just describe what you want in plain English — Claude picks the right tool automatically.
Log your work as you go. Claude creates a timestamped devlog, appends entries throughout your session, and summarises at the end.
One file per day. Each meeting gets its own section with attendees and action items. Promote individual meetings to project-specific permanent notes.
Create structured specs with goals, non-goals, design decisions, and open questions. Iterate during implementation and track what changed.
Find open tasks across your vault, mark them done, and keep action items from meetings connected to your permanent notes.
Capture things you learned inline — a new API behaviour, a debugging insight, a pattern you spotted — without leaving your workflow.
Surface everything that needs attention — stale drafts, open tasks, proposed decisions, specs with unanswered questions, notes missing wikilinks.
Your Obsidian vault becomes Claude's memory inside Codespace — specs, bug notes, and context you already wrote flow directly into the code session. No copy-paste, no re-explaining.
Write the feature spec in Obsidian — goals, non-goals, design decisions. Open Codespace and say "read my caching spec and implement the TTL logic in src/cache.ts." Claude reads your design intent and the actual code simultaneously, no copy-paste.
Log observed behavior, error messages, and hypotheses in Obsidian as you debug. In Codespace: "read my auth bug investigation and look at src/auth/ — what am I missing?" Your notes become the diagnostic brief — no re-explaining symptoms from scratch.
End your session by logging "what I did, what broke, what's next" in your devlog. Next Codespace — even a brand new one — just say "read my devlog from yesterday and tell me where I stopped." Zero mental overhead reconstructing context.
Before a PR review, jot your checklist in Obsidian — things to verify, patterns to look for, concerns from the design meeting. In Codespace: "read my review checklist for PR #142 and go through the changed files." Structured and code-aware.
Write an Architecture Decision Record capturing your chosen approach and the reasoning. Then: "read my ADR on pagination and implement it in the API following that decision." Your design intent travels intact into the implementation — no guessing what you meant.
All AI-generated notes land in Inbox/ first — drafts you can review before they become permanent. When you're happy, promote them to Notes/.
New notes go to Inbox/ with a date prefix and auto-frontmatter
Open in Obsidian, edit freely, append more content during the session
promote_note moves it to Notes/ — append-only, won't overwrite an existing note
Lives in Notes/ forever. Inbox draft deleted. Vault stays clean.
What your vault looks like after a productive day:
Each type generates the right structure automatically — no blank page, no forgotten fields.
Timestamped session log. Append entries as you work. One note per task or PR.
Structured insight — what you learned, where from, how confident. Source-first.
Feature/design spec with overview, goals, non-goals, design, open questions, decisions table.
Daily log — one file per day, each meeting as a ## HH:MM — Title section.
Architecture Decision Record — context, decision, consequences, alternatives considered.
Freeform. Source banner, body, open questions, next steps, related notes.
You never call these directly — Claude picks the right one based on what you ask. But here's what's available.
| Tool | What it does | |
|---|---|---|
| vault_summary | read | Folder counts + 10 recently modified files. Good session opener. |
| vault_review | read | Processing queue: stale drafts, open tasks, proposed decisions, specs with open questions, notes missing wikilinks. |
| vault_search | read | Full-text search across all notes. Optional folder scope and line context. |
| read_note | read | Read a note by filename (wikilink-style) or vault-relative path. |
| list_notes | read | File tree grouped by folder. |
| list_inbox | read | Inbox drafts with metadata. Filter by date or note type. |
| list_tasks | read | Find tasks across the vault. Filter by file, status, or today's daily note. |
| complete_task | write | Toggle a task done or reopen it. Partial text match, case-insensitive. |
| create_note | write | Create a new note from a type template. Always creates in Inbox/. |
| write_note | write | Create or overwrite. New files go to Inbox/, existing files updated in place. |
| append_to_note | write | Append to a note. position:top prepends (for Capture.md). Auto-updates frontmatter changelog (skipped for Capture.md). |
| promote_note | write | Move Inbox draft to Notes/. Append-only — permanent notes are never overwritten. Deletes draft. |
| rename_note | write | Rename or move a note within the vault. |
| delete_note | write | Move to Trash/ (recoverable). |
Pick your AI client first — the steps are different.
/mcp add — works on any OSPick your setup — the installer handles everything automatically.
The MCP server runs as a local process — no tunnel, nothing to keep running.
After both are installed, open a new PowerShell window.
Sets up Obsidian, vault folders, and registers the MCP server automatically.
The MCP server runs as a local process — no tunnel, nothing to keep running.
brew install node or nodejs.orgAsks for your vault path, scaffolds folders, saves env vars to ~/.zshrc, and registers the MCP server in ~/.claude.json.
Your vault lives on your local Windows machine. Your Codespace runs in GitHub's cloud and can't reach localhost directly — so start.ps1 creates a secure Cloudflare connection that gives your Codespace a temporary URL to reach the vault. Nothing is stored; the connection closes when you stop the script.
Prerequisite: run the local installer first — it sets the vault path and auth token automatically.
⚠️ Only run the local installer steps above if you also use Claude Code locally. Skip them if you only use Codespaces.
Download and run — keep it running while you work in the Codespace.
Paste the curl command printed by step 1. This writes the MCP config into your Codespace.
Run /mcp inside Claude, click Authenticate — a browser tab opens and auto-closes. Then exit and start a new Claude session. The 14 vault tools are now live.
⚠️ You must start a new Claude session after authenticating — the token is loaded at startup, not mid-session.
Automate with dotfiles: copy dotfiles/install.sh into your GitHub dotfiles repo → GitHub Settings → Codespaces → Dotfiles. Every new Codespace gets a setup-obsidian <url> shell function — skip the curl step entirely.
Inside a Copilot CLI session, run /mcp add and fill in each prompt:
obsidian
2 — STDIO
npx obsidian-ai-mcp@latest
OBSIDIAN_VAULT=C:\path\to\vault
*
Node.js 18+ must be installed. The vault tools all work — whether Copilot follows your vault_context.md preferences depends on the model.
Once installed, just open Claude and talk to it. No commands to memorize — describe what you want and Claude picks the right tool.
Run /mcp at the start of every session to confirm the vault is live. If you see 0 tools, exit and re-run claude.
Notes stay in Inbox/ until you promote them. Promoted notes move to Notes/ and are never overwritten.
Need a separate vault for work vs personal? Run switch-vault.ps1 — it updates both the environment variable and the MCP registration in one step, without re-running the full installer.
Shows your current vault, asks for the new path, scaffolds Inbox/, Notes/, Capture.md, vault.config.yaml, and vault_context.md if missing, then updates everything.
Changes take effect in the next Claude session. Run /mcp to confirm 14 tools are connected to the new vault.