Obsidian MCP Server

Connect Claude Desktop directly to your Obsidian vault.
Ask Claude to read, write, search, and organise your notes - all from a single conversation.

Video Tutorial

New to MCP or not sure where to start?
Watch the full step-by-step tutorial on YouTube:

Watch the Tutorial → youtube.com/@dojicreates

Related MCP server: Obsidian MCP Server

PDF Installation Guide

Want a printable, offline reference with screenshots for every step?

Get the PDF Guide → dojicreates.com

The guide covers installation, configuration, and example prompts you can copy and use right away.

What This Does

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. This server implements that standard and exposes your Obsidian vault as a set of tools Claude can use.

Claude Desktop  ←──── MCP (stdio) ────→  server.py  ←── file I/O ──→  Obsidian Vault

• Runs 100% locally - no cloud service, no Obsidian plugin, no API keys

• Claude can only access files inside your vault - nothing else on your machine

• Works on Windows and macOS

Folder Structure

mcp/
├── .venv/              ← isolated Python environment (created during setup)
├── server.py           ← the MCP server
├── config.json         ← your vault path goes here (not committed to git)
├── requirements.txt    ← Python dependencies
├── start_server.bat    ← optional: run the server manually on Windows
└── README.md           ← this file

Prerequisites

• Python 3.10+ installed

• Claude Desktop installed

• An Obsidian vault on your machine

Setup (5 minutes)

Step 1 - Download this project

Click Code → Download ZIP on this page and extract it anywhere on your machine,
or clone it with git:

git clone https://github.com/YOUR_USERNAME/obsidian-mcp-server.git
cd obsidian-mcp-server

Step 2 - Create the Python virtual environment

Open a terminal inside the project folder and run:

Windows (PowerShell or Command Prompt):

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

macOS / Linux:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Step 3 - Set your vault path

Open config.json and replace the placeholder with the real path to your Obsidian vault:

{
  "vault_path": "C:/Users/YOUR_USERNAME/Documents/YourVaultName"
}

How to find your vault path in Obsidian:
Settings → Files and links → Vault path (shown at the top of that section).

Use forward slashes / even on Windows, or escape backslashes with \\.

config.json is listed in .gitignore - it will not be pushed to GitHub, keeping your personal path private.

Step 4 - Connect Claude Desktop

Claude Desktop reads its MCP server list from a config file.

Find the config file:

Open that file in any text editor. If it does not exist, create it.

Add this block, replacing the paths with the actual location of your project folder:

Windows example:

{
  "mcpServers": {
    "obsidian": {
      "command": "C:\\Users\\YOUR_USERNAME\\path\\to\\mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\mcp\\server.py"],
      "env": {}
    }
  }
}

macOS example:

{
  "mcpServers": {
    "obsidian": {
      "command": "/Users/YOUR_USERNAME/path/to/mcp/.venv/bin/python",
      "args": ["/Users/YOUR_USERNAME/path/to/mcp/server.py"],
      "env": {}
    }
  }
}

If the file already has other MCP servers, add the "obsidian": { ... } block inside the existing "mcpServers" object. Do not create a second "mcpServers" key.

Save the file, then fully quit and reopen Claude Desktop.
On Windows: right-click the system tray icon → Quit, then relaunch.

Step 5 - Verify it works

In Claude Desktop, start a new conversation and type:

"List all my notes"

or

"Show me the vault structure"

You should see a tool icon appear in the chat interface - that means Claude is connected to your vault.

Available Tools

All paths are relative to the vault root.
Example: "Ideas/Project Alpha.md" - not the full system path.

Example Prompts

"Search my notes for anything about machine learning"

"Create a note called Meeting Notes in my Work folder with today's action items"

"Add a task to my daily note: review project proposal"

"Show me everything in my Projects folder"

"Move my draft essay from Drafts/Essay.md to Published/Essay.md"

Changing the Vault Path

Edit config.json and update vault_path. Restart Claude Desktop after saving.

Alternatively, you can skip config.json entirely and set an environment variable:

OBSIDIAN_VAULT_PATH=C:/Users/YOUR_USERNAME/Documents/YourVaultName

The environment variable takes priority over config.json.

Troubleshooting

Claude doesn't show the tool icon / server not found

1. Double-check the paths in claude_desktop_config.json - use double backslashes \\ on Windows.

2. Make sure you fully quit Claude Desktop (not just closed the window) and relaunched it.

3. Test the server manually by opening a terminal and running:

   # Windows
   .venv\Scripts\python.exe server.py
   
   # macOS / Linux
   .venv/bin/python server.py

   It should print nothing and wait - that means it is working. Press Ctrl+C to stop.

"Vault path not set" error

config.json is missing or vault_path is empty. Make sure config.json exists in the same folder as server.py and contains a valid path.

"Path escapes the vault root" error

You passed an absolute path instead of a vault-relative path.
Use "Ideas/note.md" not "C:/Users/.../Ideas/note.md".

Notes not showing up

Make sure vault_path points to the root of your vault - the folder that contains the .obsidian hidden folder, not a subfolder inside it.

Re-installing dependencies

If you ever delete .venv or move the project to a new folder, run setup again:

# Windows
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

How It Works (Technical)

server.py uses the FastMCP helper from Anthropic's mcp Python SDK.

• Each function decorated with @mcp.tool() becomes a callable tool in Claude.

• Claude Desktop launches python server.py as a child process when needed.

• Communication happens over stdin/stdout using JSON-RPC - no network port is opened.

• No authentication is required. Everything stays on your local machine.

Built using Anthropic's official MCP Python SDK (FastMCP).

Claude Desktop
  │
  ├─[spawn]──→ python server.py
  │
  ├─[stdin]──→ {"method":"tools/call","params":{"name":"read_note","arguments":{"path":"..."}}}
  │
  └─[stdout]←─ {"result":{"content":[{"type":"text","text":"..."}]}}

Security

• The server only accesses files inside your vault directory. Any path that tries to escape (e.g. ../../sensitive-file) is blocked at the code level.

• No data is sent anywhere - everything runs locally.

• Claude cannot execute shell commands or access anything outside the vault.

License

MIT - free to use, modify, and distribute.

Made with care. If this helped you, consider sharing it or leaving a star on GitHub.
More tools and tutorials at dojicreates.com