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

---

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:

OS	Location
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json

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

Tool	What it does
read_note(path)	Read the full content of a note
write_note(path, content)	Create or overwrite a note
append_to_note(path, content)	Add text to the end of a note
delete_note(path)	Permanently delete a note
list_notes(folder?)	List all .md files (optionally inside a folder)
search_notes(query, folder?, case_sensitive?)	Full-text / regex search across notes
get_vault_structure(max_depth?)	Tree view of folders and files
move_note(source, destination)	Move or rename a note
get_or_create_daily_note(date?)	Get today's daily note; creates it from a template if absent

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