README.md
An MCP server that exposes your Obsidian vault to AI assistants
mcp-obsidian
An MCP server that exposes your Obsidian vault to AI assistants via the Model Context Protocol.
Requirements
- Python 3.12+
- uv
Installation
git clone https://github.com/johnkang/mcp-obsidian
cd mcp-obsidian
uv sync
Usage
Set the OBSIDIAN_VAULT_PATH environment variable to the absolute path of your vault, then run the server:
OBSIDIAN_VAULT_PATH=/path/to/your/vault uv run mcp-obsidian
Claude Desktop Integration
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-obsidian", "mcp-obsidian"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
}
}
}
}
The config file is located at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Tools
File Operations
| Tool | Description |
|---|---|
list_files(path="") |
List files and folders in the vault or a subdirectory |
read_note(path) |
Read the contents of a note |
write_note(path, content) |
Create or overwrite a note (parent dirs created automatically) |
append_to_note(path, content) |
Append content to the end of an existing note |
delete_note(path) |
Delete a note or folder |
move_note(src, dest) |
Move or rename a note within the vault |
Search
| Tool | Description |
|---|---|
search_notes(query) |
Case-insensitive full-text search across all .md files |
search_by_tag(tag) |
Find all notes containing a specific tag |
Frontmatter
| Tool | Description |
|---|---|
get_frontmatter(path) |
Read the YAML frontmatter of a note |
update_frontmatter(path, key, value) |
Set or update a frontmatter field (creates it if absent) |
Links & Graph
| Tool | Description |
|---|---|
get_backlinks(path) |
Find all notes that link to a given note via [[wikilinks]] |
get_outlinks(path) |
Extract all [[wikilinks]] from a note |
get_orphans() |
Find notes with no incoming or outgoing links |
Daily Notes
| Tool | Description |
|---|---|
get_daily_note(date_str="") |
Read the daily note for a date (defaults to today, format: YYYY-MM-DD) |
create_daily_note(date_str="") |
Create a daily note, using a daily template from Templates/ if available |
Utility
| Tool | Description |
|---|---|
list_tags() |
List all tags in the vault with usage counts |
get_recent_notes(n=10) |
List the N most recently modified notes |
get_note_stats() |
Return vault statistics (note count, word count, tags, links) |
list_templates() |
List all templates in the vault's Templates/ folder |
Security
All file paths are validated to prevent path traversal attacks — no operation can escape the configured vault directory.
Tools (19)
list_filesList files and folders in the vault or a subdirectoryread_noteRead the contents of a notewrite_noteCreate or overwrite a noteappend_to_noteAppend content to the end of an existing notedelete_noteDelete a note or foldermove_noteMove or rename a note within the vaultsearch_notesCase-insensitive full-text search across all .md filessearch_by_tagFind all notes containing a specific tagget_frontmatterRead the YAML frontmatter of a noteupdate_frontmatterSet or update a frontmatter fieldget_backlinksFind all notes that link to a given noteget_outlinksExtract all wikilinks from a noteget_orphansFind notes with no incoming or outgoing linksget_daily_noteRead the daily note for a datecreate_daily_noteCreate a daily notelist_tagsList all tags in the vault with usage countsget_recent_notesList the N most recently modified notesget_note_statsReturn vault statisticslist_templatesList all templates in the vault's Templates folderEnvironment Variables
OBSIDIAN_VAULT_PATHrequiredThe absolute path to your Obsidian vaultConfiguration
claude_desktop_config.json
{"mcpServers": {"obsidian": {"command": "uv", "args": ["run", "--directory", "/path/to/mcp-obsidian", "mcp-obsidian"], "env": {"OBSIDIAN_VAULT_PATH": "/path/to/your/vault"}}}}Try it
→Search my notes for any mentions of 'project alpha' and summarize the current status.
→List all my recent notes from the last week and identify any that are orphans.
→Create a new daily note for today and add a checklist of my top 3 priorities.
→Find all notes tagged with #research and extract their frontmatter to a summary table.
→What are the most linked notes in my vault?