# Obsidian MCP Server

Exposes Obsidian vaults as MCP (Model Context Protocol) tools. Runs on Windows, reachable from WSL2, Hermes Agent, or any MCP-compatible client.

## Tools Provided

| Tool | Description |
|------|-------------|
| `get_vaults` | List all vaults in the vaults root directory |
| `get_vault_directories` | Browse directory structure within a vault |
| `get_vault_document` | Read a markdown note by path |
| `search_vault` | Full-text search across all notes in a vault |
| `get_recent_changes` | Recently modified notes, newest first |
| `get_backlinks` | Find all notes linking to a given note via [[wikilinks]] |
| `create_document` | Create a new markdown note |
| `edit_document` | Overwrite an existing markdown note |

## Setup (Windows)

### 1. Prerequisites

- Python 3.10+ installed on Windows ([python.org](https://python.org))
- Recommended: `uv` for package management (`pip install uv`)

### 2. Install

```cmd
cd C:\path\to\obsidian-mcp-server
pip install -r requirements.txt
```

Or with uv:
```cmd
uv pip install -r requirements.txt
```

### 3. Configure

Copy and edit the config file:
```cmd
copy config.example.json config.json
```

Edit `config.json` — set `vaults_root` to the folder containing your Obsidian vaults:
```json
{
    "vaults_root": "D:\\Obsidian"
}
```

Alternatively, set the environment variable:
```cmd
set OBSIDIAN_VAULTS_ROOT=D:\Obsidian
```

Or pass it on the command line:
```cmd
python server.py --vaults-root "D:\Obsidian"
```

Priority: CLI arg > env var > config.json

### 4. Run

```cmd
python server.py
```

Or use the launcher script (auto-restarts on crash):
```cmd
start.bat
```

Output:
```
Obsidian MCP Server
  Vaults root: D:\Obsidian
  Listening:   http://0.0.0.0:8765/mcp
  Vaults found: 2
```

### 5. Windows Firewall

If connecting from WSL2 or another machine, allow Python through Windows Firewall on port 8765:

```powershell
New-NetFirewallRule -DisplayName "Obsidian MCP" -Direction Inbound -Protocol TCP -LocalPort 8765 -Action Allow
```

## Connecting from Hermes Agent (WSL2)

### Find Windows Host IP from WSL2

```bash
# The gateway IP from WSL2 IS the Windows host
ip route | grep default | awk '{print $3}'
# Usually 192.168.1.x or 172.x.x.x
```

Typical output: `172.30.112.1` or your LAN IP like `192.168.1.100`.

### Add to Hermes config

Edit `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  obsidian:
    url: "http://192.168.1.100:8765/mcp"
    timeout: 60
    connect_timeout: 30
```

Replace `192.168.1.100` with your actual Windows IP.

Then reload MCP servers:
```
/reload-mcp
```

Tools will appear as:
- `mcp_obsidian_get_vaults`
- `mcp_obsidian_get_vault_directories`
- `mcp_obsidian_get_vault_document`
- `mcp_obsidian_search_vault`
- `mcp_obsidian_get_recent_changes`
- `mcp_obsidian_get_backlinks`
- `mcp_obsidian_create_document`
- `mcp_obsidian_edit_document`

## Security

- Binds to `0.0.0.0` by default for LAN access. On a trusted home network behind NAT, this is fine.
- No authentication — relies on network isolation. Don't expose to the internet.
- Path traversal is prevented — all vault paths are validated to stay within the vault root.
- Hidden directories (`.obsidian`, `.trash`, `.git`) are excluded from listings and search.

## Example Queries via Hermes

```
> List my vaults
> Search the SKT vault for "Klauth"
> Get recent changes in the SKT vault, last 10
> Read the note "Session-Notes/Session-12" from the SKT vault
> Find all notes linking to "Adonis" in the SKT vault
> Create a new note "Ideas/dragon-lore.md" in my D&D vault
```