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
.mdfiles 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