Content
# 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](https://www.youtube.com/@dojicreates/videos)**
---
## PDF Installation Guide
Want a printable, offline reference with screenshots for every step?
**[Get the PDF Guide → dojicreates.com](https://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+](https://www.python.org/downloads/) installed
- [Claude Desktop](https://claude.ai/download) installed
- An [Obsidian](https://obsidian.md/) 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:
```bash
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):**
```powershell
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```
**macOS / Linux:**
```bash
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:
```json
{
"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:**
```json
{
"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:**
```json
{
"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:
```powershell
# Windows
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```
```bash
# 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](https://dojicreates.com/)*
