Claude Code + Obsidian: How to Integrate Them for an AI Markdown Workflow

If you keep your second brain in Obsidian and you’re already using Claude Code for
development work, you’re sitting on one of the most underrated AI
productivity setups available right now. Your notes are plain markdown
files in a folder. Claude Code is an AI agent that lives in your
terminal and reads, writes, and reasons over plain markdown files in a
folder. The integration is almost too obvious — and once you wire it up,
the workflow you get is dramatically better than anything a chatbot
interface can give you.

This guide walks through how to integrate Obsidian with Claude Code,
how to set up the Obsidian MCP server for deeper context, and the
markdown workflow we recommend for getting real leverage out of the
pairing. No fluff, no theory — just the setup and the workflows that
make it pay off.

Why
Obsidian + Claude Code Is the Best AI Markdown Workflow

Most AI tools want you to paste your context into a chat window every
time. That’s fine for a one-off question. It’s terrible for ongoing work
where the context is your entire knowledge base.

Obsidian solves the storage problem: your notes are markdown files on
your local disk, organized in a vault, with backlinks and metadata that
you control. Claude Code solves the reasoning problem: it’s an agentic
CLI that can read your files, edit them, run commands, and follow
multi-step instructions. Together they give you something neither tool
delivers alone — an AI assistant that has full read/write access to your
second brain and can act on it like a teammate.

A few reasons this combination outperforms ChatGPT-with-uploads or a
notebook plugin:

• Your vault stays local. No uploading, no
  third-party storage, no copy-pasting context windows. Claude Code reads
  files directly from disk.
• It’s bidirectional. Claude Code can not only
  summarize your notes — it can rewrite them, reorganize them, generate
  new ones, and fix link rot.
• It scales. Claude Code handles vaults with
  thousands of notes. Long conversations stay grounded in your actual
  files instead of hallucinated context.
• It composes with the rest of your toolchain.
  Because Claude Code is a real CLI, you can chain it with git, scripts,
  and any other terminal workflow you already use.

If you live in markdown, this is the AI workflow to build around.

How to
Integrate Obsidian with Claude Code: Step-by-Step

Here’s the simplest possible integration — no plugins, no MCP, no
extra software. This is what we recommend starting with before adding
any complexity.

Step 1 — Install Claude Code. If you don’t already
have it, install Claude Code from Anthropic. It runs as a terminal
command and works on macOS, Linux, and Windows (via WSL).

Step 2 — Open your Obsidian vault directory in your
terminal. Your vault is just a folder. Navigate to it:

cd ~/Documents/MyVault

Replace MyVault with whatever your vault is actually
named.

Step 3 — Launch Claude Code from inside the
vault.

claude

That’s it. Claude Code now has the vault as its working directory. It
can read every markdown file, every folder, every attachment. You can
ask it questions like “summarize my notes from this week,” “find every
note that mentions Project X,” or “create a new note in the Clients
folder for Acme Corp with our standard template.”

Step 4 — Try a real prompt. Don’t start with toy
examples. Try one of these:

• “Read all the notes I’ve written this month and write a summary of
  what I’ve been working on.”
• “Find every note tagged #idea and group them into themes.”
• “Open my CRM note for [client name] and draft a follow-up email
  based on what’s in there.”

You’ll know within five minutes whether this workflow is going to
change your life. For most people who already keep good notes, it
does.

Step 5 — Add a CLAUDE.md to your vault. This is the
single highest-leverage upgrade you can make. We cover it in detail
below.

That’s the whole basic integration. No plugins, no servers, no
configuration files. Just point Claude Code at your vault and start
working.

How to
Set Up the Obsidian MCP Server for Claude Code

The basic file-access setup above is enough for 80% of use cases. But
if you want Claude Code to understand Obsidian’s specific features —
backlinks, tags, the graph view, frontmatter, daily notes — you’ll want
to add an MCP server.

What is MCP? MCP (Model Context Protocol)
is the open standard Anthropic released for giving Claude access to
external tools and data. An MCP server is a small program that exposes
capabilities Claude can call. There are MCP servers for databases, APIs,
GitHub, Slack — and yes, for Obsidian.

What does an Obsidian MCP server give you? Beyond
raw file access, an MCP server can expose Obsidian-aware operations:
“list all backlinks to this note,” “find notes by tag,” “open the daily
note for today,” “search the vault by content with proper ranking.”
Claude Code can then call those operations directly instead of grepping
files manually.

Setup overview:

1. Install Node.js if you don’t have it. Most MCP
   servers run on Node.
2. Install a community Obsidian MCP server. Search
   GitHub for “obsidian mcp server” — there are several active community
   implementations. Pick one that’s recently maintained and that matches
   the Obsidian features you actually use (backlinks, tags, daily notes,
   etc.).
3. Point the MCP server at your vault path. Most
   servers take a --vault argument or read it from a config
   file.
4. Register the server with Claude Code. Claude Code
   reads MCP server config from a JSON file in your home directory or
   project directory. Add an entry that points to the MCP server binary,
   with your vault path as an argument.
5. Restart Claude Code. It should pick up the new MCP
   tools automatically. Run /mcp inside Claude Code to confirm
   the server is connected and to see the tools it exposes.
6. Test it. Ask Claude Code something only an
   Obsidian-aware tool can answer well, like “show me all backlinks to my
   note titled ‘Q2 Strategy’.”

When to use the MCP server vs. just file access: If
you’re mostly reading and writing notes, file access is enough. If
you’re doing graph-aware analysis (finding orphan notes, mapping topic
clusters, working with backlinks programmatically), the MCP server is
worth the setup. For a full deep dive — picking a server, configuring
it, and integrating it cleanly with Claude Code — see our complete Obsidian
MCP server setup guide.

The
Claude Code + Obsidian Markdown Workflow in Practice

Setup is the easy part. The interesting question is what to actually
do with this once it’s working. Here are the markdown workflows we’ve
seen produce real leverage. (For a deeper treatment of the end-to-end
workflow — from raw notes to shipped work — see our breakdown of the Claude
Code markdown workflow, and for more day-to-day patterns, our daily
workflows for Claude Code + Obsidian power users.)

Meeting notes to action
items

You finish a meeting. Your notes are messy bullet points in a daily
note. Open Claude Code and say: “Read today’s daily note, extract every
action item I committed to, and create a new note called ‘Action items —
[date]’ with each one as a checkbox. Tag it #followups.” Done in
seconds. Now you have a structured task list pulled from unstructured
notes — every time, automatically.

Research vault to blog
drafts

You’ve been collecting research on a topic for weeks. Notes scattered
across your vault, all tagged #research/ai-automation. Tell Claude Code:
“Read every note tagged #research/ai-automation, identify the three
strongest themes, and draft a blog post outline that hits each one with
supporting points pulled from my notes.” You go from “I have a lot of
notes on this” to “I have a real outline” in one prompt.

Client knowledge bases

Each of your clients has a folder in your vault. Inside, you keep
meeting notes, account info, strategy docs, campaign briefs. Before a
client call, ask: “Catch me up on Acme Corp. Read everything in their
folder, summarize the current state of the engagement, and flag anything
urgent.” You walk into the call sharp without spending 30 minutes
re-reading.

Daily journaling to weekly
reviews

You journal in daily notes. At the end of the week, ask: “Read this
week’s daily notes. Summarize what I worked on, what I struggled with,
and what I want to carry into next week. Save it as ‘Weekly review —
[date].’” The compounding effect of this over a year is hard to
overstate.

Vault hygiene and link
health

“Find every orphan note in my vault — notes with no backlinks.” “Find
every broken link.” “Find duplicate notes that should probably be
merged.” Claude Code can run these audits on demand and either fix the
issues directly or hand you a list to review.

The pattern under all of this: your vault becomes both the
input and the output of an AI agent that knows your context.
That’s what no chatbot can do.

CLAUDE.md Meets Your
Obsidian Vault

This is the one thing we’d ask you to add today, even if you change
nothing else. Drop a CLAUDE.md file in the root of your
vault. Claude Code reads it automatically every time you launch.

What goes in it:

• Vault structure. “Daily notes are in
  /Daily/. Client work is in /Clients/{name}/.
  Ideas live in /Inbox/ until processed.”
• Conventions. “Tags use kebab-case. Action items are
  checkboxes. Every client folder has a 00-README.md with the
  engagement brief.”
• Your voice. “When generating notes, write in first
  person, lowercase, terse. No corporate jargon.”
• Templates. “When I ask for a ‘meeting note,’ use
  the template in /Templates/meeting.md.”
• Things to avoid. “Never modify notes in
  /Archive/. Never delete notes — move them to
  /Trash/ instead.”

Once this file exists, every Claude Code session in the vault starts
with this context loaded. You stop having to repeat yourself. You stop
having to micromanage formatting. The agent behaves like someone who’s
worked in your vault for months.

Treat your CLAUDE.md as a living document. Every time you correct
Claude Code on the same thing twice, add a line to CLAUDE.md so you
never have to correct it a third time.

Building a Content
Pipeline From Notes

For anyone publishing content — newsletter, blog, podcast, social —
the Obsidian + Claude Code combo is the closest thing to an editorial
assistant you can build without hiring one.

Step 1 — Capture in Obsidian. Anytime you have a
content idea, drop it in /Inbox/ as a quick note. Don’t
structure it. Just capture.

Step 2 — Process in batches. Once a week, ask Claude
Code: “Read every note in my Inbox folder. For each one, decide if it’s
a viable content idea. If yes, move it to /Content/Ideas/
with a one-line hook and three supporting bullets. If no, archive
it.”

Step 3 — Outline on demand. When you sit down to
write, pick an idea note and ask: “Outline a 1,500-word post from this
idea. Pull supporting examples from my vault wherever you can find
them.”

Step 4 — Draft and revise. Ask Claude Code to draft
against the outline. Then iterate: “Tighten the intro.” “Add a section
on X.” “Cut anything that sounds like jargon.” Because everything is a
markdown file, every revision is just a file edit you can diff and roll
back.

It’s the kind of pipeline that scales cleanly from a single
newsletter to a full editorial program — and once it’s running, the
marginal cost of one more piece of content drops dramatically.

Advanced:
Obsidian as Project Memory for Claude Code

Here’s the upside-down version of the workflow: instead of using
Claude Code to manage your Obsidian vault, use Obsidian as Claude Code’s
long-term memory across projects.

Claude Code sessions are stateful within a session and stateless
across sessions. That’s a problem if you’re working on a long-running
project — every new session means re-explaining context. The fix: keep a
/Projects/{name}/ folder in your Obsidian vault with a
STATE.md, a DECISIONS.md, and a running
JOURNAL.md. At the end of each session, ask Claude Code to
update those files with what was learned, decided, or completed. At the
start of the next session, point Claude Code at the folder and let it
catch itself up.

You’ve now built a memory layer for Claude Code using nothing but
markdown files. That memory is portable, version-controllable (the vault
is a git repo, right?), and human-readable.

Frequently Asked Questions

Can Claude Code read Obsidian vaults directly? Yes.
An Obsidian vault is just a folder of markdown files on disk. Claude
Code can read, write, and edit those files directly when you launch it
from the vault directory. No plugin required for basic access.

Is there an Obsidian MCP server for Claude Code? Yes
— multiple community-maintained MCP servers expose Obsidian-specific
operations (backlinks, tags, daily notes, search) to Claude Code. They
live on GitHub. We recommend starting with raw file access first and
adding an MCP server only when you need graph-aware operations.

Does Claude Code work with markdown notes outside
Obsidian? Yes. Claude Code doesn’t care whether the markdown
lives in an Obsidian vault, a Notion export, a Bear vault, or a plain
folder. Anything markdown-based works the same way. Obsidian is just our
preferred home for the notes because of its plain-text storage and graph
features.

How is Claude Code different from Claude Desktop for working
with notes? Claude Desktop is a chat interface — you upload
files or paste content into a conversation. Claude Code is an agent in
your terminal — it reads, writes, and edits files in place, runs
multi-step workflows, and can chain commands. For ongoing work in a
notes vault, Claude Code wins easily. For one-off questions, Claude
Desktop is fine.

Will this work on Windows? Yes — install Claude Code
in WSL (Windows Subsystem for Linux) or use the native Windows build if
available. Point it at your vault path the same way you would on macOS
or Linux.

Is my vault data safe? Claude Code reads files
locally from your machine. It sends excerpts to Anthropic’s API as
needed to answer your prompts, the same way any LLM-powered tool does.
If you have notes that should never leave your machine, exclude those
folders from sessions or ask Claude Code to ignore them in your
CLAUDE.md.

Bringing It Together

Obsidian + Claude Code isn’t just an integration — it’s a
fundamentally different way to work with knowledge. Your notes stop
being a passive archive and start being an active workspace that an AI
agent can read, reason over, and contribute to.

If you’re already in Obsidian, the only thing standing between you
and this workflow is fifteen minutes of setup. Start with file access.
Add a CLAUDE.md. Try one of the workflows above on a real task you’re
avoiding. The leverage compounds fast.

If you’d like help designing an AI-powered knowledge or content
system around Claude Code and Obsidian — for yourself, your team, or
your business — let’s design
your system. It’s what we do.