# Obsidian Vault MCP Server

An [MCP](https://modelcontextprotocol.io) server that gives Claude full read/write access to your [Obsidian](https://obsidian.md) vault. Works with Claude Code and Claude Desktop.

## What it does

Gives Claude 10 tools to work with your vault:

| Tool | Description |
|------|-------------|
| `search_vault` | Full-text search across all notes |
| `read_note` | Read a note's content |
| `list_recent` | List recently modified notes |
| `list_folder` | Browse folders and notes |
| `search_tags` | Find notes by `#tag` |
| `create_note` | Create a new note |
| `update_note` | Replace or append to a note |
| `delete_note` | Delete a note |
| `create_folder` | Create a new folder |
| `move_note` | Move or rename a note |

## Quick start

### 1. Clone and build

```bash
git clone <this-repo>
cd obsidian-vault-mcp
npm install
npm run build
```

### 2. Find your vault path

Your Obsidian vault is just a folder on your filesystem. You need the absolute path to it.

**Common locations:**

- macOS: `~/Documents/My Vault` or `~/Obsidian`
- Windows: `C:\Users\YourName\Documents\My Vault`
- Linux: `~/Documents/My Vault`
- iCloud (macOS): `~/Library/Mobile Documents/iCloud~md~obsidian/Documents/My Vault`
- Google Drive: `~/Library/CloudStorage/GoogleDrive-you@gmail.com/My Drive/My Vault`

**To check:** open Obsidian, click the vault icon (bottom-left), and look at the path shown under your vault name.

### 3. Configure Claude

Pick the setup that matches how you use Claude.

---

#### Option A: Claude Code

Add to `~/.claude/mcp.json` (create the file if it doesn't exist):

```json
{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
      }
    }
  }
}
```

Then restart Claude Code.

---

#### Option B: Claude Desktop

Open Claude Desktop settings (gear icon) > Developer > Edit Config, and add:

```json
{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
      }
    }
  }
}
```

Then restart Claude Desktop.

---

### 4. Test it

Ask Claude:

> "List the folders in my Obsidian vault"

or

> "Search my vault for notes about project planning"

## Requirements

- **Node.js** 18+
- **Obsidian vault** (any vault — it reads/writes markdown files directly)
- **ripgrep** (optional, but makes search much faster)

### Installing ripgrep (recommended)

Search is ~10x faster with [ripgrep](https://github.com/BurntSushi/ripgrep). Without it, the server falls back to a basic Node.js file search which works fine for smaller vaults.

```bash
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows (with Chocolatey)
choco install ripgrep

# Windows (with Scoop)
scoop install ripgrep
```

## How it works

The server reads and writes `.md` files directly on your filesystem — it doesn't go through the Obsidian app or its API. This means:

- Obsidian doesn't need to be running
- Changes sync instantly (Obsidian picks them up when it's open)
- It works with any sync setup (iCloud, Google Drive, Syncthing, etc.)
- Only `.md` files are visible — attachments, images, and hidden files are ignored

## Permissions note

This server has **full read/write access** to your vault. Claude can create, edit, move, and delete notes. If you want read-only access, remove the write tools (`create_note`, `update_note`, `delete_note`, `create_folder`, `move_note`) from the source, or deny those tools in your Claude Code permissions.

## Troubleshooting

**"Missing required environment variable: OBSIDIAN_VAULT_PATH"**
You haven't set the vault path. Check your config — `OBSIDIAN_VAULT_PATH` must be set in the `env` block.

**"Vault path does not exist"**
The path is wrong. Double-check the absolute path to your vault folder. Make sure there are no typos, and that you're using the right path separator for your OS.

**"Cannot find module" errors**
Run `npm run build` — the TypeScript needs to be compiled to JavaScript first.

**Search returns no results but you know the content exists**
If ripgrep isn't installed, the fallback search is slower and may time out on very large vaults. Install ripgrep for better performance.

**Claude doesn't see the tools**
Restart Claude Code or Claude Desktop after changing the config. Check the MCP server logs in Claude Desktop (Developer > Logs).