Obsidian MCP

MCP server for Obsidian vault management. Designed for AI agents (Claude Desktop, Claude Code).

Features

• Full CRUD operations on notes
• Wikilink management (auto-update on rename/delete)
• Frontmatter manipulation
• Tag-based and content search
• Backlinks discovery
• Section-level operations

Installation

poetry install

Configuration

Set the vault path via environment variable:

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

# WSL example (Windows vault accessed from WSL)
export OBSIDIAN_VAULT_PATH="/mnt/c/Users/username/Documents/Obsidian/my_vault"

Claude Desktop Configuration

Add to claude_desktop_config.json:

Linux/macOS:

{
  "mcpServers": {
    "obsidian": {
      "command": "bash",
      "args": ["-c", "cd /path/to/obsidian-mcp && poetry run obs-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Windows (via WSL):

{
  "mcpServers": {
    "obsidian": {
      "command": "wsl",
      "args": [
        "-e", "bash", "-c",
        "cd /path/to/obsidian-mcp && poetry run obs-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/mnt/c/Users/username/Documents/Obsidian/my_vault"
      }
    }
  }
}

Available Tools

Tool	Description
read_note(name)	Read note content (frontmatter + body)
create_note(name, content?, frontmatter?)	Create note
append_note(name, text)	Append to note
update_note(name, content)	Replace body, preserve frontmatter
delete_note(name, dry_run?)	Delete (links updated to [[name (deleted)]])
rename_note(old_name, new_name, dry_run?)	Rename + update wikilinks
search_notes(query, mode?)	Search (name, name_partial, content, tag)
get_links(name, direction?)	Get incoming/outgoing links
get_note_metadata(name)	Get frontmatter + links without body
set_frontmatter(name, key, value)	Set frontmatter key
add_tag(name, tag)	Add tag to note
remove_tag(name, tag)	Remove tag from note
list_notes(limit?, offset?)	List all notes (paginated)
replace_text(name, old, new, replace_all?)	Replace text in note
insert_text(name, text, before?, after?)	Insert text at position
read_section(name, section)	Read section by heading
append_section(name, section, text)	Append to section
update_section(name, section, content)	Replace section content
delete_section(name, section)	Delete section
get_headings(name)	Get all headings
find_broken_links()	Find broken wikilinks
get_help()	Get tool descriptions

Vault Structure

• Flat structure (all .md files in vault root)
• YAML frontmatter with --- delimiters
• Wikilinks: [[Note Name]]
• Tags in frontmatter: tags: [tag1, tag2]
• .trash/ for deleted notes
• .obsidian/ ignored

Development

# Run tests
poetry run pytest tests/spec/core/ -v

# Lint
poetry run ruff check src/
poetry run mypy src/

License

MIT