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)
• Recommended: uv for package management (pip install uv)

2. Install

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

Or with uv:

uv pip install -r requirements.txt

3. Configure

Copy and edit the config file:

copy config.example.json config.json

Edit config.json — set vaults_root to the folder containing your Obsidian vaults:

{
    "vaults_root": "D:\\Obsidian"
}

Alternatively, set the environment variable:

set OBSIDIAN_VAULTS_ROOT=D:\Obsidian

Or pass it on the command line:

python server.py --vaults-root "D:\Obsidian"

Priority: CLI arg > env var > config.json

4. Run

python server.py

Or use the launcher script (auto-restarts on crash):

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:

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

Connecting from Hermes Agent (WSL2)

Find Windows Host IP from WSL2

# 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:

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