README.md
MCP server for Obsidian vault management.
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
Tools (22)
read_noteRead note content including frontmatter and body.create_noteCreate a new note.append_noteAppend text to a note.update_noteReplace note body while preserving frontmatter.delete_noteDelete a note and update links.rename_noteRename a note and update associated wikilinks.search_notesSearch notes by name, partial name, content, or tag.get_linksGet incoming or outgoing links for a note.get_note_metadataGet frontmatter and links without the body.set_frontmatterSet a specific frontmatter key.add_tagAdd a tag to a note.remove_tagRemove a tag from a note.list_notesList all notes in the vault.replace_textReplace text within a note.insert_textInsert text at a specific position.read_sectionRead a specific section by heading.append_sectionAppend text to a specific section.update_sectionReplace content of a specific section.delete_sectionDelete a specific section from a note.get_headingsGet all headings from a note.find_broken_linksFind all broken wikilinks in the vault.get_helpGet descriptions for all available tools.Environment Variables
OBSIDIAN_VAULT_PATHrequiredThe absolute file system path to your Obsidian vault.Configuration
claude_desktop_config.json
{"mcpServers": {"obsidian": {"command": "bash", "args": ["-c", "cd /path/to/obsidian-mcp && poetry run obs-mcp"], "env": {"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"}}}}Try it
→Search my notes for any mentions of 'project roadmap' and summarize them.
→Create a new note titled 'Meeting Notes' with the current date in the frontmatter.
→Find all broken wikilinks in my vault and list them for me.
→Add the tag 'todo' to the note titled 'Research Ideas'.
→Read the 'Summary' section of my 'Project Alpha' note.