# mcp-obsidian

An MCP server that exposes your [Obsidian](https://obsidian.md) vault to AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io).

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)

## Installation

```bash
git clone https://github.com/johnkang/mcp-obsidian
cd mcp-obsidian
uv sync
```

## Usage

Set the `OBSIDIAN_VAULT_PATH` environment variable to the absolute path of your vault, then run the server:

```bash
OBSIDIAN_VAULT_PATH=/path/to/your/vault uv run mcp-obsidian
```

## Claude Desktop Integration

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-obsidian", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}
```

The config file is located at:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

## Tools

### File Operations

| Tool | Description |
|------|-------------|
| `list_files(path="")` | List files and folders in the vault or a subdirectory |
| `read_note(path)` | Read the contents of a note |
| `write_note(path, content)` | Create or overwrite a note (parent dirs created automatically) |
| `append_to_note(path, content)` | Append content to the end of an existing note |
| `delete_note(path)` | Delete a note or folder |
| `move_note(src, dest)` | Move or rename a note within the vault |

### Search

| Tool | Description |
|------|-------------|
| `search_notes(query)` | Case-insensitive full-text search across all `.md` files |
| `search_by_tag(tag)` | Find all notes containing a specific tag |

### Frontmatter

| Tool | Description |
|------|-------------|
| `get_frontmatter(path)` | Read the YAML frontmatter of a note |
| `update_frontmatter(path, key, value)` | Set or update a frontmatter field (creates it if absent) |

### Links & Graph

| Tool | Description |
|------|-------------|
| `get_backlinks(path)` | Find all notes that link to a given note via `[[wikilinks]]` |
| `get_outlinks(path)` | Extract all `[[wikilinks]]` from a note |
| `get_orphans()` | Find notes with no incoming or outgoing links |

### Daily Notes

| Tool | Description |
|------|-------------|
| `get_daily_note(date_str="")` | Read the daily note for a date (defaults to today, format: `YYYY-MM-DD`) |
| `create_daily_note(date_str="")` | Create a daily note, using a daily template from `Templates/` if available |

### Utility

| Tool | Description |
|------|-------------|
| `list_tags()` | List all tags in the vault with usage counts |
| `get_recent_notes(n=10)` | List the N most recently modified notes |
| `get_note_stats()` | Return vault statistics (note count, word count, tags, links) |
| `list_templates()` | List all templates in the vault's `Templates/` folder |

## Security

All file paths are validated to prevent path traversal attacks — no operation can escape the configured vault directory.