create_or_update_note
Create or update a note with content and frontmatter. Performs upsert operation - creates if doesn't exist, updates if it does.
LABSCO SUMMARY
Vault-shaped tools instead of a file API bolted onto an assistant.
The difference shows in create_or_update_note and get_daily_note: both remove a decision the assistant would otherwise get wrong — does this note exist, and what is today's note actually called. find_related_notes is the one that pays off on a mature vault, because it uses the links you already made rather than keyword luck.
What it is
An MCP server that talks to a locally running Obsidian REST API. Alongside plain file operations it exposes vault-level ideas: daily notes, recently modified notes, frontmatter keys, and notes related by tags or links.
What you get
- list_directory with pagination, so exploring a large vault does not flood the context
- read_file, write_file with overwrite, append or prepend modes, and delete_item for files and directories
- create_or_update_note — an upsert with content and frontmatter, so the assistant never has to ask whether the note exists
- get_daily_note for a given date, handling the usual daily-note naming and folder conventions
- get_recent_notes, ordered by modification time
- search_vault across content, filenames and metadata, with path filtering
- find_related_notes — notes connected by shared tags, links or backlinks
- get_metadata_keys and get_metadata_values, to see what frontmatter the vault actually uses
- get_note and list_notes, kept for compatibility with earlier setups
Requirements
Obsidian with the Local REST API running and reachable at an address you configure. A bearer token is optional and only needed if that API asks for one. Runs on Node or Bun.
Setup effort
One command — npx obsidian-local-rest-api-mcp
USE CASES
01
Appending to today's note without knowing its filename
Fetch the daily note for a date, then append to it — the naming convention is handled for you.
02
Capturing something into the vault when you are not sure it exists
Upsert the note with content and frontmatter in one call instead of checking first.
03
Finding what you already wrote on a topic
Search content, filenames and tags together, then pull the note that matches.
04
Following the connections you already made
Start from one note and surface the ones sharing its tags, links or backlinks.
05
Auditing frontmatter across a vault
List which frontmatter keys exist, then see every value used for one of them.
13 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
delete_item
Delete a file or directory from the vault
find_related_notes
Find notes related to a given note based on shared tags, links, or backlinks
get_daily_note
Get daily note for a specific date. Handles common daily note naming conventions and file locations.
get_metadata_keys
Get all available frontmatter keys from notes
get_metadata_values
Get all unique values for a specific frontmatter key
get_note
Get a specific note with its content and metadata (legacy)
get_recent_notes
Get recently modified notes, ordered by modification time
list_directory
List directory contents with pagination to prevent context overflow. Shows immediate contents by default.
list_notes
List all notes in the vault with optional search filter (legacy with search support)
read_file
Read content of a specific file from the vault
search_vault
Search vault content across files, filenames, and metadata with advanced filtering
write_file
Write file content with different modes: overwrite (default), append, or prepend. Handles both create and update operations.
BEFORE YOU INSTALL
What to know first
Tools you get
13 tools when we connected.
Requires
- npx on PATH
- Node.js 18+
CONTEXT COST
Light Standing cost
Rated by the size of the 13 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx obsidian-local-rest-api-mcpMCP Clients
Claude Desktop
Set OBSIDIAN_API_URL to the address of your running Obsidian Local REST API: http://obsidian-local-rest-api.test only works for a Laravel Valet setup — otherwise use your own address, such as http://localhost:8000. Leave out OBSIDIAN_API_KEY if your API does not require a key:
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"obsidian-vault": {
"command": "npx",
"args": [
"obsidian-local-rest-api-mcp"
],
"env": {
"OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
"OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>"
}
}
}
}Cherry Studio
Set OBSIDIAN_API_URL to the address of your running Obsidian Local REST API: http://obsidian-local-rest-api.test only works for a Laravel Valet setup — otherwise use your own address, such as http://localhost:8000. Leave out OBSIDIAN_API_KEY if your API does not require a key:
CHERRY STUDIO · JSON
{
"Name": "obsidian-vault",
"Type": "Standard Input/Output (stdio)",
"Command": "npx",
"Arguments": "obsidian-local-rest-api-mcp",
"Environment Variables": {
"OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
"OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>"
}
}
