helm
37df28e159
StreamableHTTP MCP server exposing Obsidian vaults as tools. - 8 tools: list_vault, get_vaults, get_vault_document, search_vault, get_recent_changes, get_backlinks, create_document, edit_document - FastMCP framework with path traversal prevention - Cross-OS transport (WSL2->Windows via HTTP)
147 lines
No EOL
3.5 KiB
Markdown
147 lines
No EOL
3.5 KiB
Markdown
# 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
|
|
``` |