Obsidian MCP

MCP server for Obsidian vaults that wraps the official Obsidian CLI (1.12+), so Claude can read, search and write notes.

เอกสาร

Obsidian MCP

npm License: MIT Node.js CodeQL CI Conventional Commits CodeRabbit

Access your Obsidian vault from Claude Desktop, Claude Code, and other AI tools that support the Model Context Protocol.

Obsidian 1.12 introduced a powerful CLI, but it isn't directly accessible from GUI-based AI tools like Claude Desktop. This MCP server bridges that gap — giving any MCP-compatible client full access to your vault through 34 tools and prompt templates.

Features: read/write/search notes, manage properties and tasks, run pre-built prompt workflows — all validated with Zod schemas and powered by the official Obsidian CLI.

Prerequisites

  • Obsidian 1.12+ (tested through 1.12.7) with the CLI enabled: Settings → General → Advanced → Command Line Interface → Enable
  • Obsidian app must be running (the CLI communicates with the app)

Setup

Install the package from npm and configure your MCP client to use it. The server runs locally on your machine and communicates with the Obsidian app via its CLI.

How it works

Your machine
┌─────────────────────────────┐
│ Claude Desktop / Claude Code│
│   ↕ stdio (stdin/stdout)    │
│ obsidian-mcp (Node.js)      │ ──CLI──→  Obsidian App (running)
└─────────────────────────────┘

Each user runs the server locally via npx. The server receives tool calls from Claude over stdio and executes Obsidian CLI commands against the running app.

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@zethictech/obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT": "MyVault"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add obsidian --env OBSIDIAN_VAULT="My Vault" -- npx -y @zethictech/obsidian-mcp

To make it available across all projects, add --scope user:

claude mcp add obsidian --scope user --env OBSIDIAN_VAULT="My Vault" -- npx -y @zethictech/obsidian-mcp

The -- separator is required so the command and its args aren't parsed as claude mcp add flags.

Environment Variables

VariableRequiredDescription
OBSIDIAN_VAULTYesVault name or ID
OBSIDIAN_CLI_PATHNoOverride path to obsidian binary (auto-detected by default)
OBSIDIAN_TIMEOUTNoCLI timeout in milliseconds (default: 30000)

Available Tools (34)

Read-only tools (20)

ToolDescription
read_noteRead the full content of a note
get_file_infoGet metadata about a file
list_filesList files in the vault
list_foldersList folders in the vault
searchSearch the vault for text
search_with_contextSearch with surrounding line context
get_backlinksList incoming links to a note
get_linksList outgoing links from a note
find_unresolved_linksFind broken/unresolved links
find_orphan_notesFind notes with no incoming links
get_outlineGet heading structure of a note
get_propertiesList frontmatter properties
read_propertyRead a specific property value
list_tagsList tags in the vault or a note
list_tasksList tasks (checkboxes)
daily_readRead today's daily note
daily_pathGet the daily note file path
get_vault_infoGet vault info (name, path, size)
wordcountCount words/characters in a note
get_helpGet CLI help for any command

Write tools (9)

ToolDescription
create_noteCreate a new note
append_noteAppend content to a note
prepend_notePrepend content to a note
set_propertySet a frontmatter property
daily_createOpen/create today's daily note
daily_appendAppend to today's daily note
daily_prependPrepend to today's daily note
update_taskToggle or update a task's status
add_bookmarkAdd a bookmark

Destructive tools (5)

ToolDescription
move_noteMove a note (updates all links)
rename_noteRename a note (updates all links)
delete_noteDelete a note (trash or permanent)
remove_propertyRemove a frontmatter property
run_commandRun any CLI command directly

run_command is an escape hatch that gives you access to all ~100 CLI commands not covered by the structured tools above (sync, plugins, themes, templates, workspaces, publish, dev tools, etc.). Use get_help to discover available commands.

All tool inputs are validated at runtime using Zod schemas. Invalid inputs return clear error messages before any CLI command is executed.


Prompts

Five pre-built MCP Prompts provide templated workflows. These gather vault data via CLI calls and return structured messages for the LLM.

PromptArgumentsDescription
analyze_vault—Vault health overview: orphan notes, unresolved links, tags
summarize_notefile requiredRead and summarize a specific note
find_relatedfile requiredFind related notes via backlinks, links, and shared tags
daily_review—Review today's daily note and suggest follow-up actions
suggest_linksfile requiredSuggest wikilinks to add based on note content

Troubleshooting

Server not starting?

  • Verify OBSIDIAN_VAULT is set and matches your vault name exactly
  • Ensure Obsidian 1.12+ is installed with the CLI enabled
  • Run npx @zethictech/obsidian-mcp --version to verify the package loads

Obsidian app not detected?

  • The CLI requires Obsidian to be running — start the app and try again
  • If Obsidian just launched, wait a few seconds for it to fully initialize

Stale npx cache?

npx --yes @zethictech/obsidian-mcp

License

MIT

Built by Zethic

obsidian-mcp is built and maintained by Zethic, a software and AI engineering studio in Bengaluru.

Need AI assistants built on your team's knowledge? We do agentic AI development — hire dedicated engineers or talk to us about consulting →