README.md
Interact with your Obsidian vault through the Local REST API plugin
MCP server for Obsidian (TypeScript + Bun)
A Model-Context-Protocol (MCP) server that lets Claude (or any MCP-compatible LLM) interact with your Obsidian vault through the **Local REST API** community plugin – written in TypeScript and runnable with bunx.
✨ Components
Tools
| Tool name | Description |
|---|---|
| obsidian_status | Returns basic details about the Obsidian Local REST API server and your authentication status |
| obsidian_delete_active | Deletes the note that is currently active in the Obsidian UI |
| obsidian_get_active | Retrieves the full content of the active note (Markdown or JSON view) |
| obsidian_patch_active | Inserts, replaces or prepends content in the active note relative to a heading, block reference, or front-matter field |
| obsidian_post_active | Appends Markdown to the end of the active note |
| obsidian_put_active | Replaces the entire body of the active note |
| obsidian_get_commands | Lists every command available in Obsidian’s command palette |
| obsidian_execute_command | Executes a specific Obsidian command by its ID |
| obsidian_open_file | Opens the given file inside Obsidian (creates it if missing); optional flag to open in a new leaf |
| obsidian_delete_periodic | Deletes the current daily / weekly / monthly / quarterly / yearly note for the requested period |
| obsidian_get_periodic | Returns the content of the current periodic note for the requested period |
| obsidian_patch_periodic | Inserts / replaces content in a periodic note relative to a heading, block reference, or front-matter field |
| obsidian_post_periodic | Appends Markdown to the periodic note (creates it if it doesn’t exist) |
| obsidian_put_periodic | Replaces the entire body of a periodic note |
| obsidian_search_dataview | Runs a Dataview-DQL query across the vault and returns matching rows |
| obsidian_search_json_logic | Runs a JsonLogic query against structured note metadata |
| obsidian_simple_search | Performs a plain-text fuzzy search with optional surrounding context |
| obsidian_list_vault_root | Lists all files and directories at the root of your vault |
| obsidian_list_vault_directory | Lists files and directories inside a specific folder of the vault |
| obsidian_delete_file | Deletes a specific file (or directory) in the vault |
| obsidian_get_file | Retrieves the content of a file in the vault (Markdown or JSON view) |
| obsidian_patch_file | Inserts / replaces content in an arbitrary file relative to a heading, block reference, or front-matter field |
| obsidian_post_file | Appends Markdown to a file (creates it if it doesn’t exist) |
| obsidian_put_file | Creates a new file or replaces the entire body of an existing file |
See Obsidian's Local REST API specifications for more details.
Example prompts
# Summarize the latest “architecture call” note
# (Claude will transparently call list_files_in_vault → get_file_contents)
Get the contents of the last “architecture call” note and summarize them.
# Find all mentions of Cosmos DB
Search for all files where “Azure CosmosDb” is mentioned and explain the context briefly.
# Create a summary note
Summarize yesterday’s meeting and save it as “summaries/2025-04-24-meeting.md”. Add a short intro suitable for e-mail.
⚙️ Configuration
Obsidian REST API key
There are two ways to pass the Obsidian API key to the server:
- Server config (recommended) – pass it via the
envfield in your Claude (or other client) MCP-server declaration:
// claude_desktop_config.json
{
"mcpServers": {
"@fazer-ai/mcp-obsidian": {
"command": "bunx",
"args": ["@fazer-ai/mcp-obsidian@latest"],
"env": {
"OBSIDIAN_API_KEY": "your-obsidian-api-key"
}
}
}
}
[!NOTE] Use
@fazer-ai/mcp-obsidian@latestto ensure you always run the most up to date version of the server.
- Alternatively, you can use an
.envfile. Place the key in the.envyou created above. Note it must be placed in the working directory where the MCP server is running.
Environment variables
You can use the .env.example file as reference to create your own .env file.
OBSIDIAN_API_KEY= # Obtain this from the plugin settings in Obsidian
OBSIDIAN_PROTOCOL=http
OBSIDIAN_HOST=localhost
OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to
🛠 Development
Running local version on Claude Desktop
After cloning this repo, you can update Claude's config to run your local version of the server instead of pulling from npm. This is useful for quickly testing change
Tools (24)
obsidian_statusReturns basic details about the Obsidian Local REST API server and your authentication statusobsidian_delete_activeDeletes the note that is currently active in the Obsidian UIobsidian_get_activeRetrieves the full content of the active noteobsidian_patch_activeInserts, replaces or prepends content in the active noteobsidian_post_activeAppends Markdown to the end of the active noteobsidian_put_activeReplaces the entire body of the active noteobsidian_get_commandsLists every command available in Obsidian’s command paletteobsidian_execute_commandExecutes a specific Obsidian command by its IDobsidian_open_fileOpens the given file inside Obsidianobsidian_delete_periodicDeletes the current daily, weekly, monthly, quarterly, or yearly noteobsidian_get_periodicReturns the content of the current periodic noteobsidian_patch_periodicInserts or replaces content in a periodic noteobsidian_post_periodicAppends Markdown to the periodic noteobsidian_put_periodicReplaces the entire body of a periodic noteobsidian_search_dataviewRuns a Dataview-DQL query across the vaultobsidian_search_json_logicRuns a JsonLogic query against structured note metadataobsidian_simple_searchPerforms a plain-text fuzzy searchobsidian_list_vault_rootLists all files and directories at the root of your vaultobsidian_list_vault_directoryLists files and directories inside a specific folderobsidian_delete_fileDeletes a specific file or directory in the vaultobsidian_get_fileRetrieves the content of a file in the vaultobsidian_patch_fileInserts or replaces content in an arbitrary fileobsidian_post_fileAppends Markdown to a fileobsidian_put_fileCreates a new file or replaces the entire body of an existing fileEnvironment Variables
OBSIDIAN_API_KEYrequiredAPI key obtained from the Local REST API plugin settings in ObsidianOBSIDIAN_PROTOCOLProtocol for the REST API (e.g., http)OBSIDIAN_HOSTHost address for the REST APIOBSIDIAN_PORTPort the Local REST API plugin is bound toConfiguration
claude_desktop_config.json
{"mcpServers": {"@fazer-ai/mcp-obsidian": {"command": "bunx", "args": ["@fazer-ai/mcp-obsidian@latest"], "env": {"OBSIDIAN_API_KEY": "your-obsidian-api-key"}}}}Try it
→Get the contents of the last 'architecture call' note and summarize them.
→Search for all files where 'Azure CosmosDb' is mentioned and explain the context briefly.
→Summarize yesterday’s meeting and save it as 'summaries/2025-04-24-meeting.md'.
→List all files in my 'projects' folder and tell me which ones were modified recently.