Connect Obsidian to Claude via MCP

Chat with your Obsidian vault using Claude Desktop and Model Context Protocol.

Introduction

30 Second Summary

You've built an Obsidian vault full of notes, ideas, and research. But getting answers out of it means manually searching, scrolling through files, and piecing together connections yourself.

In this project, you will connect your Obsidian vault to Claude Desktop using the Model Context Protocol, so you can chat with your second brain in natural language and have it read, search, rewrite, and create notes for you.

What You'll Build

You'll open Claude Desktop, ask a question about something buried deep in your vault, and get an answer grounded in your own notes rather than generic AI knowledge.

By the end of this project, you'll have:

  • A live MCP connection between Claude Desktop and your Obsidian vault, letting you ask questions and get answers pulled directly from your own notes.
  • A semantic search workflow that finds relevant notes across your entire vault, even without exact keyword matches.
  • A read-write loop where Claude rewrites messy notes into clearer versions and saves them directly back to your vault as clean Markdown files.
  • **Secret Mission:** Connect ChatGPT Desktop to the same vault so you can work with your second brain from either AI assistant.

Are there any prerequisites?

You need an existing Obsidian vault with notes on your Mac and Claude Desktop installed with an active subscription. If you have both, you're ready to go.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters to you.

Install Node.js

The MCP server that connects Claude Desktop to your Obsidian vault runs on Node.js. Without Node.js installed, Claude Desktop cannot launch the server process that bridges the gap between your conversations and your vault files.

In this step, you'll check whether Node.js is already on your Mac and install it if needed.

In this step, get ready to:
  • Check if Node.js is already installed on your Mac.
  • Install Node.js v20 or higher if needed.
  • Verify the installation works by confirming the version number.
Check your Node.js version
  • Press Cmd+Space to open Spotlight search.
  • Type Terminal and press Enter to open it.
  • Check your Node.js version by running this command:
node --version

You'll see one of three results. Find the tab that matches what you see:

✔️ I see version 20 or higher

Your terminal printed something like v24.19.0 or v22.5.0. Any version number starting with v20 or above means Node.js is ready.

The MCP server will use this to run whenever Claude Desktop starts a conversation. You're all set for the next step.

ⓧ I see a version lower than 20

Your terminal printed a version like v18.17.0 or v16.20.0. The Obsidian MCP server requires Node.js v20 or higher, so you need to upgrade.

  • Open the Node.js download page in your browser:
  • https://nodejs.org/en/download
  • The page defaults to the LTS (Long Term Support) version, which is v24 or newer. Click the download button for macOS.
  • Open the downloaded .pkg file and follow the installer prompts. Accept the defaults at each step.
  • Once the installer finishes, close your Terminal window completely.
  • Open a new Terminal window (Cmd+Space, type Terminal, press Enter).

Before you run the version check again, what version number do you expect to see now?

  • Verify the upgrade by running this command:
node --version

You should see v24 or higher printed. The installer replaces your older version with the new one.

Still seeing the old version?

Make sure you opened a fresh Terminal window after installation. Existing windows keep the old path loaded.

If you previously installed Node.js through a version manager like nvm, the manager may override the system install. Run nvm install --lts to update through your version manager instead.

help me troubleshoot my Node.js version after upgrading on macOS

ⓧ Command not found

Your terminal printed something like command not found: node. Node.js is not installed on your Mac yet.

  • Open the Node.js download page in your browser:
  • https://nodejs.org/en/download
  • The page defaults to the LTS (Long Term Support) version, which is v24 or newer. Click the download button for macOS.
  • Open the downloaded .pkg file and follow the installer prompts. Accept the defaults at each step.
  • Once the installer finishes, close your Terminal window completely.
  • Open a new Terminal window (Cmd+Space, type Terminal, press Enter).

Before you run the version check, what do you expect to see if the install worked?

  • Verify the installation by running this command:
node --version

You should see v24 or higher printed. Any version of v20+ works for this project.

Still seeing command not found?

Make sure you opened a brand new Terminal window after the installer completed. The old window does not know about newly installed programs.

If you're still stuck, try restarting your Mac and opening Terminal fresh. The installer adds Node.js to your system path, but a restart guarantees it takes effect.

help me get Node.js working on my Mac

Why does the MCP server need Node.js?

The Obsidian MCP server (@istrejo/obsidian-mcp) is a Node.js program. When Claude Desktop opens a conversation, it launches this program in the background using the node runtime. The server reads and writes your vault files, then passes the results back to Claude.

You won't need to run Node.js commands yourself after this step. Claude Desktop handles launching the server automatically.

Node.js is ready on your Mac. Next up, you'll tell Claude Desktop where your Obsidian vault lives and which MCP server to use.

Configure the MCP Connection

Node.js is installed and ready to power MCP servers on your Mac. The next piece is telling Claude Desktop where your Obsidian vault lives and which server to launch when you start a conversation.

Claude Desktop uses a JSON configuration file to know which MCP servers are available. You'll create this file, point it at your vault, and restart Claude so it picks up the new connection.

In this step, get ready to:
  • Open (or create) the Claude Desktop configuration file.
  • Add the Obsidian MCP server entry with your vault path.
  • Restart Claude Desktop and confirm the connection.
Open the Claude Desktop configuration file

Claude Desktop looks for a configuration file at a specific path on your Mac. If you've never configured an MCP server before, this file won't exist yet.

  • Return to your Terminal and run these commands to ensure the file exists and open it in TextEdit:
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

What do these commands do?

  • mkdir -p creates the Claude folder if it doesn't already exist (it probably does).
  • touch creates the config file if it doesn't exist, or leaves it unchanged if it does.
  • open -a TextEdit opens the file in macOS TextEdit so you can edit it.

TextEdit opens with the file. If you just created it, the file will be empty.

TextEdit not opening?

Make sure you included the backslash before the space in Application\ Support. The backslash tells Terminal to treat the space as part of the folder name.

If you prefer a different text editor (like VS Code or nano), feel free to open the file at ~/Library/Application Support/Claude/claude_desktop_config.json in whatever editor you're comfortable with.

Still stuck? Help me open the Claude Desktop config file on macOS.

Add the Obsidian MCP server configuration

This JSON configuration tells Claude Desktop to launch the Obsidian MCP server and connect it to your vault whenever you open a conversation.

  • If the file is empty, paste the following configuration into TextEdit. Replace the vault path with the absolute path to your own Obsidian vault:
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@istrejo/obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "[[VAULT_PATH=\"/Users/yourname/Documents/MyVault\"]]"
      }
    }
  }
}

What does this configuration do?

  • mcpServers is the top-level object where all your MCP server connections live.
  • obsidian is the name Claude Desktop uses to identify this server.
  • command and args tell Claude to run npx -y @istrejo/obsidian-mcp to start the server.
  • OBSIDIAN_VAULT_PATH is the environment variable that tells the server exactly which folder on your Mac contains your vault files.

Finding your vault's absolute path

Open Finder, navigate to your Obsidian vault folder, then right-click the folder and hold the Option key. You'll see Copy "FolderName" as Pathname appear in the menu. Click it to copy the full path (e.g. /Users/alex/Documents/SecondBrain).

Paste this path into the configuration in place of the placeholder. Make sure you keep the surrounding quotes.

Already have MCP servers configured?

If your file already has content with other servers inside mcpServers, add the obsidian entry alongside them (separated by a comma) rather than replacing everything.

  • Save the file by pressing Cmd+S.
  • Close TextEdit.
Restart Claude Desktop and verify the connection

Claude Desktop only reads its configuration file when it launches. Closing the window is not enough. You need to fully quit the app so it restarts fresh with the new config.

  • Press Cmd+Q to fully quit Claude Desktop.
  • Press Cmd+Space to open Spotlight, type Claude, and press Enter to reopen it.
  • Open a new conversation in Claude Desktop.

Before you check, what do you think you'll see if the configuration worked?

  • Look for a hammer icon near the chat input area at the bottom of the conversation. Click it to see the list of available tools.

You should see obsidian listed as a connected MCP server with its tools available. This confirms Claude Desktop successfully launched the Obsidian MCP server and connected to your vault.

Don't see the hammer icon or obsidian tools?

  • Make sure you fully quit Claude Desktop with Cmd+Q before reopening. Just closing the window does not restart the app.
  • Double-check that your JSON is valid. A missing comma, extra comma, or mismatched brace will silently break the config. Compare yours against the example above character by character.
  • Confirm your vault path is an absolute path starting with /Users/. Relative paths or paths starting with ~/ will not work here.

Claude Desktop won't launch my Obsidian MCP server. Help me debug my claude_desktop_config.json file.

Your MCP bridge is live. Next up, you'll put it to work by chatting with your vault and proving Claude can reach your actual notes.

Chat With Your Vault

The connection between Claude Desktop and your vault is configured. You can see the obsidian tools listed in the interface. But you haven't yet proven that Claude can actually reach into your vault and pull back real content from your own notes.

In this step, you'll put the connection to the test. You'll ask Claude to read your files, answer questions grounded in your notes, and find connections across your vault.

In this step, get ready to:
  • Confirm Claude can see and list your vault's files.
  • Get an answer from Claude that's grounded in your own notes, not general knowledge.
  • Ask Claude to find connections between notes in your vault.
Confirm Claude can see your files

The simplest proof that the MCP connection works is asking Claude to list what it can see. If it returns real file names from your vault, the bridge is live.

  • In Claude Desktop, open a new conversation.
  • Type a prompt asking Claude to list your notes. For example:

"List all the notes in my vault."

  • Press Enter to send the message.

Claude will use the obsidian tools to read your vault's directory. You should see a list of actual file names from your Obsidian vault appear in the response.

What should I see?

Claude's response should include file names and folder names you recognize from your vault. You might see it call a tool like list_notes or search_notes before showing results.

If you have a large vault, try narrowing the request to a specific folder: "List the notes in my Projects folder."

Claude not using the vault tools?

If Claude responds with something generic like "I don't have access to your files," the MCP connection may not be active.

  • Check that you fully quit Claude Desktop with Cmd+Q and reopened it after editing the config file in the previous step.
  • Click the tools icon near the chat input and confirm "obsidian" appears in the list of connected servers.
  • If "obsidian" is missing, double-check your claude_desktop_config.json for typos in the server entry.

Need more help? Help me troubleshoot why Claude Desktop isn't connecting to my Obsidian vault via MCP.

Ask a question grounded in your notes

Listing files proves the connection exists. The next test proves Claude can read the actual content of your notes and use it to answer questions.

  • Think of a topic you know you've written about in your vault. Pick something specific enough that you'd recognize your own words in the answer.
  • Ask Claude a question about that topic. For example:

"What have I written about [your topic]?"

  • Send the message and read Claude's response carefully.

Before you read the response, ask yourself: does this answer contain your own words, your own ideas, or your own structure? Or does it sound like a generic explanation anyone could write?

What if Claude answers from general knowledge?

Sometimes Claude will answer a broad question from its training data instead of searching your vault first. This is normal. You can steer it explicitly.

Try rephrasing with a direct instruction like: "Search my vault for notes about [topic]" or "Read the note at [path/to/note.md] and summarize it." This tells Claude to use the vault tools rather than relying on general knowledge.

  • If your first response came from general knowledge, send a follow-up prompt that explicitly asks Claude to search or read from your vault.
  • Confirm the response now contains specific phrases, ideas, or structure you recognize from your own notes.

Build a prompting habit

Starting your prompts with "In my vault..." or "Search my notes for..." consistently triggers Claude to use the vault tools first. Over time, Claude will default to checking your vault when you ask knowledge questions in conversations where the tools are active.

Find connections between your notes

A second brain becomes powerful when you can surface connections you didn't know existed. Claude can search across your entire vault and find notes that relate to a single concept, even if they use different terminology.

  • Pick a concept or theme that might appear across multiple notes in your vault.
  • Ask Claude to find connections. For example:

"What notes in my vault relate to [concept]?"

  • Send the message and review the results.

Claude should return multiple notes and explain how each one connects to your concept. Look for results that reference actual file names and quote or paraphrase content you recognize.

Only getting one or two results?

  • Try a broader concept that you know spans multiple notes.
  • Ask Claude to search more broadly: "Search my entire vault for anything related to [concept], including notes that mention it indirectly."
  • If your vault is small, this is expected. Claude can only find connections in notes that exist.

Still stuck? Help me get better results when asking Claude to find connections across my Obsidian vault.

You've confirmed that Claude can read, search, and surface connections from your vault. Your second brain is now a conversational knowledge base. Next up, you'll put the write side to work and improve your notes directly through chat.

Improve Your Vault Through Chat

In the last step, you confirmed that Claude can reach into your vault and return answers grounded in your own notes. That covers the reading side of the equation.

Now it's time to unlock the real payoff. The true power of connecting your second brain to a chat interface is being able to prune, reframe, and improve notes through conversation instead of manual editing. You'll pick a note that needs work, ask Claude to restructure it, and have the improved version saved directly back to your vault.

In this step, get ready to:
  • Ask Claude to read a messy note and suggest improvements.
  • Have Claude rewrite the note and save it back to your vault.
  • Verify the changes appear in Obsidian as a proper Markdown file.
Ask Claude to read a note and suggest improvements

Every vault has notes that could use some love. Maybe the structure is inconsistent, the language is unclear, or the ideas trail off mid-thought.

  • Think of one note in your vault that feels messy, outdated, or incomplete. You should know roughly where it lives (the folder and filename).
  • Switch back to your Claude Desktop conversation.
  • Ask Claude to read the note by giving it the path. For example, type something like: "Read my note at Projects/my-project and tell me what could be improved."

Claude reads the full content of your note and returns suggestions. You should see it identify specific problems: unclear headings, missing structure, redundant sections, or incomplete thoughts.

What is Claude doing behind the scenes?

When you ask Claude to read a note, it calls the read_note tool from the MCP server. This reads the raw file from your vault's filesystem and returns the full content to Claude, including any YAML frontmatter.

Claude then uses its own reasoning to analyze the writing quality and suggest improvements. The MCP server handles the file access. Claude handles the thinking.

Choose a note you can compare

Pick a note where you already know what "better" looks like. That way you can evaluate whether Claude's rewrite actually improves it. A short note (under 500 words) is ideal for a first test.

Have Claude rewrite and save the note

Now that Claude has read the note and identified problems, you can ask it to fix them and write the result back to your vault.

  • Tell Claude what improvements you want. For example: "Rewrite this note with clearer headings, tighter language, and save it back to the same path."
  • Claude will use the vault tools to overwrite the note with the improved version. Watch for a confirmation message indicating it used the update_note tool to save.

Claude should confirm it saved the note. You'll see a message like "I've updated the note at [path]" along with a summary of what changed.

Is it safe to let Claude overwrite my notes?

The MCP server has built-in safety features. Before any deletion, it automatically creates a backup copy in .obsidian-mcp-trash/{timestamp}/ inside your vault. This means you can always recover a previous version if something goes wrong.

For extra caution, you can ask Claude to show you the rewritten version first before saving. Review the changes in the chat, then explicitly tell Claude to save.

Claude not saving changes?

If Claude says it cannot write to the vault, check that OBSIDIAN_READ_ONLY is not set to true in your config. The default is false, which allows writes.

If Claude provides the rewritten content but doesn't save it, try prompting more explicitly: "Use the update_note tool to replace the content of [path] with the rewritten version above."

Why isn't Claude saving changes back to my Obsidian vault?

Verify the changes in Obsidian

The real proof is seeing the changes in your actual vault files. Before you check, take a moment to predict what you expect to see.

  • What do you think the note will look like in Obsidian? Will it have Claude's new headings? Will the original content be gone?
  • Open Obsidian on your Mac.
  • Navigate to the note you just had Claude rewrite.
  • Confirm the content reflects Claude's improvements: new headings, cleaner language, or restructured sections. The file should be valid Markdown that renders properly in Obsidian's preview mode.

The note now shows Claude's rewritten content. The structure matches what Claude described in the chat, saved as a clean Markdown file in your vault.

Note looks unchanged in Obsidian?

Obsidian sometimes caches file content. Try clicking away to a different note and then clicking back. You can also close and reopen the note's tab.

If the file genuinely hasn't changed, go back to Claude Desktop and ask: "Did you successfully save the updated note?" Claude should confirm whether the write operation succeeded or encountered an error.

My note in Obsidian doesn't show the changes Claude made.

Secret mission

Connect ChatGPT Desktop Too

Your vault is your knowledge, not any single AI tool's. What if you could chat with your second brain from ChatGPT Desktop too? In this secret mission, you'll connect the same Obsidian vault to ChatGPT Desktop, giving you two AI interfaces to your notes.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely locally, so there are no ongoing costs. Decide whether to keep your MCP connections active, pause them, or remove them entirely.

Resources you used:

  • MCP server configuration in ~/Library/Application Support/Claude/claude_desktop_config.json (no cost, runs only while Claude Desktop is open).
  • ChatGPT Desktop MCP configuration in ~/.codex/config.toml (Secret Mission only, no cost).

What about Node.js?

Node.js remains installed on your system. It has no ongoing cost and is useful for many other tools and projects. There is no official uninstall command for the macOS installer, so it stays on your machine unless you manually remove it.

Keep everything running

No action needed. Choose this if you want Claude Desktop (and ChatGPT Desktop) to keep connecting to your vault automatically.

  • The MCP server starts automatically when you open Claude Desktop and stops when you quit it.
  • Your vault files are never modified unless you explicitly ask Claude or ChatGPT to write changes.
  • Node.js remains installed on your system at no cost.

Pause - I'll come back to this later

Shut down the AI apps to stop the MCP server processes. Your configuration files stay in place so the connections resume next time you open the apps.

  • Fully quit Claude Desktop by pressing Cmd+Q (not just closing the window).
  • Fully quit ChatGPT Desktop by pressing Cmd+Q if you completed the Secret Mission.
  • The MCP servers stop immediately. Your vault files are unchanged.

Delete - I don't want to use this again

Remove the MCP configurations so your AI apps no longer connect to your vault. Your vault notes remain untouched.

Remove the Claude Desktop MCP connection:

  • Open ~/Library/Application Support/Claude/claude_desktop_config.json in any text editor.
  • Delete the entire obsidian entry from the mcpServers object (or delete the file entirely if this was the only server configured).
  • Fully quit Claude Desktop with Cmd+Q and reopen it. The connection is gone.

Remove the ChatGPT Desktop MCP connection (Secret Mission only):

  • Open ~/.codex/config.toml in any text editor.
  • Remove the obsidian MCP server entry.
  • Fully quit ChatGPT Desktop with Cmd+Q and reopen it.

Nice Work!

Nice Work!

You just turned your Obsidian vault into a conversational knowledge base. Your second brain is no longer a static collection of Markdown files you have to manually browse. It is a live resource you can query, improve, and grow through natural chat.

Here's what you accomplished:

  • Connected your Obsidian vault to Claude Desktop via the Model Context Protocol, giving you a chat interface to your entire second brain.
  • Queried your vault through natural language and received answers grounded in your own notes rather than generic AI knowledge.
  • Improved notes directly from chat, with changes saving back to your vault as clean Markdown files you can verify in Obsidian.
  • Secret Mission: Connected the same vault to ChatGPT Desktop, giving you two AI interfaces to your second brain.

Ready to quiz yourself?