# Obsidian MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants (like Claude) to interact directly with your Obsidian vault. This server provides comprehensive tools for managing notes, structures, and metadata.

> [!CAUTION]
> ### ⚠️ Safety Warning & Backup Notice
> This tool is still in **active development**. Since the server has write access to your Obsidian vault (including deleting and moving files), you should **absolutely create regular backups** of your vault (e.g., via Git, Dropbox, or Obsidian Sync). Use at your own risk.

## 🚀 Features

- **Full Note Management**: Create, read, update (replace, append, prepend), and delete notes.
- **Smart Search**: Full-text search, search in titles or tags, including regex support.
- **Organization**:
  - List notes and folders.
  - Automatic creation of folder structures.
  - Move and rename files with **automatic link updating**.
- **Metadata Power**:
  - Native YAML Frontmatter support.
  - Tag extraction (both inline `#tag` and in frontmatter).
  - Manage individual metadata fields.
- **Graph Functions**: Find backlinks and extract outgoing links/embeds.
- **Daily Notes**: Quick access to daily notes with template support.
- **Security**: Integrated path validation ensures operations stay within the defined vault.

## 🛠 Easy Step-by-Step Installation

Connecting your Obsidian vault to Claude is easy! Follow these 5 steps.

### 1. Install "uv" (The Engine)
This tool uses a small helper called `uv` to run.
- **Open Terminal**: Press `Cmd + Space`, type "Terminal" and hit Enter.
- **Paste this command**: Copy the line below, paste it into the Terminal, and hit Enter:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **Restart Terminal**: Close the Terminal window and open it again to finish the setup.

### 2. Prepare the Tool
1.  Download (or clone) this project to a folder on your computer.
2.  Note down the **Folder Path**. (Tip: Right-click the folder, hold the `Option` key, and select "Copy as Pathname").

### 3. Get your Obsidian Vault Path
Claude needs to know where your notes are.
1.  Open Obsidian and right-click on your Vault name (top left).
2.  Select **"Show in Finder"**.
3.  Right-click your vault folder, hold the `Option` key, and select **"Copy as Pathname"**.
    *Example: `/Users/yourname/Documents/MyNotes`*

### 4. Tell Claude about it
1.  Open **Claude Desktop**.
2.  Go to the menu: **Claude** -> **Settings...** -> **Developer**.
3.  Click **"Edit Config"**. A file will open in your text editor.
4.  Paste the following code into that file. 
    **⚠️ IMPORTANT:** Replace `/PATH/TO/TOOL/FOLDER` with the path from **Step 2**, and `/PATH/TO/YOUR/VAULT` with the path from **Step 3**.

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "run",
        "--path",
        "/PATH/TO/TOOL/FOLDER",
        "obsidian_mcp.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/PATH/TO/YOUR/VAULT"
      }
    }
  }
}
```

5.  **Save** the file and **Restart Claude Desktop**.

### 5. Confirm it Works
In a new chat with Claude, look for the **plug icon** 🔌. You can now say:
- *"Search my Obsidian notes for 'Ideas'"*
- *"Create a new note about my workout today"*
- *"What did I write in my daily note yesterday?"*

## 🧰 Available Tools

| Tool | Description |
| :--- | :--- |
| `obsidian_read_note` | Reads note content including metadata (JSON/Markdown). |
| `obsidian_create_note` | Creates a new note (automatically creates folders if needed). |
| `obsidian_update_note` | Edits notes (modes: `replace`, `append`, `prepend`). |
| `obsidian_delete_note` | Deletes notes (moves to Obsidian trash by default). |
| `obsidian_search_notes` | Powerful search across content, titles, or tags. |
| `obsidian_list_notes` | Lists notes with sorting (name, date) and pagination support. |
| `obsidian_list_folders` | Displays the folder structure of your vault. |
| `obsidian_create_folder` | Creates a new folder in the vault. |
| `obsidian_move_note` | Moves/renames notes and updates links in other notes. |
| `obsidian_get_tags` | Returns all used tags (including frequency). |
| `obsidian_get_notes_by_tag` | Finds all notes containing a specific tag. |
| `obsidian_update_frontmatter` | Allows granular updates of YAML metadata. |
| `obsidian_get_links` | Lists all outgoing links and embedded files in a note. |
| `obsidian_get_backlinks` | Shows all notes that link to the current note. |
| `obsidian_get_daily_note` | Opens or creates the daily note for a specific date. |
| `obsidian_vault_info` | Returns statistical information about the entire vault. |

## 📝 License

MIT