Obsidian MCP Server
An MCP (Model Context Protocol) server that exposes your Obsidian vault as tools for Claude. This lets any Claude session — Claude Code, Claude Desktop, claude -p scripts — read, write, search, and manage your vault.
It operates directly on vault files via Node.js fs — no Obsidian app, CLI, or plugins required. An Obsidian vault is just a folder of markdown files, and this server works with that directly.
Prerequisites
- Node.js 18+
- An Obsidian-compatible vault (any folder of markdown files)
Install
git clone <this-repo>
cd obsidian-mcp-server
npm install
npm run buildThis compiles TypeScript from src/ into build/.
Configure
Claude Code
Register the server globally so every Claude Code session has vault access:
claude mcp add --transport stdio -s user obsidian \
-e OBSIDIAN_VAULT="/path/to/your/vault" \
-- node /path/to/obsidian-mcp-server/build/index.jsThis writes to ~/.claude.json:
{
"mcpServers": {
"obsidian": {
"type": "stdio",
"command": "node",
"args": ["/path/to/obsidian-mcp-server/build/index.js"],
"env": {
"OBSIDIAN_VAULT": "/path/to/your/vault"
}
}
}
}OBSIDIAN_VAULT— path to your vault folder. If not set, the server looks for vaults in Obsidian's config (~/.config/obsidian/obsidian.jsonon Linux,~/Library/Application Support/obsidian/obsidian.jsonon macOS).
To verify it's working, start Claude Code in any project and look for the obsidian tools (they'll appear as MCP tools like vault_read, vault_search, etc.).
To remove:
claude mcp remove -s user obsidianClaude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp-server/build/index.js"],
"env": {
"OBSIDIAN_VAULT": "/path/to/your/vault"
}
}
}
}Create the file if it doesn't exist. Restart Claude Desktop after editing.
Tools
16 tools are available. All accept an optional vault parameter for multi-vault setups. If omitted, the default vault is used (set via OBSIDIAN_VAULT env var).
Read
| Tool | Description | |------|-------------| | vault_read | Read a note by name (file) or exact path (path) | | vault_daily_read | Read today's daily note | | vault_search | Full-text search across the vault. Set context: true for matching line context | | vault_files | List all files, optionally filtered by folder | | vault_tags | List all tags (sorted by count), or look up a specific tag by name | | vault_tasks | List tasks. Filter by status (todo/done) and daily (today only) | | vault_links | List outgoing links from a note | | vault_backlinks | List notes that link to a given note | | vault_properties | Read YAML frontmatter properties, or a specific property by name |
Write
| Tool | Description | |------|-------------| | vault_create | Create a new note. Supports content, template, and overwrite | | vault_append | Append content to an existing note | | vault_daily_append | Append content to today's daily note | | vault_property_set | Set a YAML frontmatter property. Supports type (text, list, number, etc.) | | vault_move | Move or rename a note | | vault_attachment | Write a binary file (image, PDF, etc.) into the vault. Returns embed syntax ![[filename]] |
Vault
| Tool | Description | |------|-------------| | vault_list | List all known Obsidian vaults |
Skills
The MCP server gives Claude the raw tools, but tools alone don't tell Claude when to use them, what vault conventions to follow, or how to structure notes. Skills provide that context.
MCP Skills (skills/) — portable, for any project
These skills are written to use the MCP tools (vault_read, vault_create, etc.). Copy them into any project where you want Claude to interact with your vault.
| Skill | Command | What it does | |-------|---------|-------------| | capture | /capture <thought> | Quick-capture a thought to today's daily note with timestamp | | log | /log <text> | Append a minimal timestamped entry to the daily note | | note | /note <title> | Create a new structured note with frontmatter and tags | | today | /today | Overview of the day — daily note, tasks, recent activity | | find | /find <query> | Deep search — text, tags, links, backlinks, synthesis | | review | /review [day\|week\|month] | Review accomplishments and outstanding items | | standup | /standup | Yesterday / Today / Blockers standup format | | tidy | /tidy <note> | Clean up a raw or voice-transcribed note |
How to add skills to a project
Copy the skills you want from this repo's skills/ directory into the target project's .claude/skills/:
# Copy all vault skills to another project
cp -r /path/to/obsidian-mcp-server/skills/* /path/to/myproject/.claude/skills/
# Or copy only specific skills
mkdir -p /path/to/myproject/.claude/skills/capture
cp /path/to/obsidian-mcp-server/skills/capture/SKILL.md /path/to/myproject/.claude/skills/capture/
mkdir -p /path/to/myproject/.claude/skills/today
cp /path/to/obsidian-mcp-server/skills/today/SKILL.md /path/to/myproject/.claude/skills/today/After copying, start Claude Code in that project and the skills will appear as /capture, /today, etc.
Choosing what to copy
You don't need all skills in every project. Pick what's relevant:
- Minimal — just
captureandtodayfor quick vault interaction - Standard — add
note,find,logfor full read/write - Full — all 8 skills for complete vault management from any project
Attachments
The vault_attachment tool handles binary files (images, PDFs, receipts, etc.) by writing them directly to the vault's filesystem. Obsidian's file watcher picks them up automatically.
Parameters:
name— filename with extension (e.g.receipt-2026-03-02.png)data— base64-encoded file contentsfolder— subfolder within vault (default:attachments)
Example workflow (e.g. from a Telegram bot):
- User sends a photo of a receipt with "Add this to expenses"
- Claude calls
vault_attachmentwith the base64-encoded image → returnsreceipt.png - Claude calls
vault_appendon an Expenses note with![[receipt.png]]to embed it
If a file with the same name already exists, a timestamp is appended to avoid overwriting. Max file size is 10 MB.
Multi-Vault
The server defaults to the vault specified by OBSIDIAN_VAULT env var. If unset, it reads Obsidian's config file to discover known vaults. To target a different vault per-call, pass the vault parameter:
vault_read(file="My Note", vault="Work Vault")Development
npm run dev # Watch mode — recompiles on save
npm run build # One-time buildThe server uses stdio transport (JSON-RPC over stdin/stdout). console.error() is used for logging — never console.log(), which would corrupt the protocol.
Project Structure
├── src/
│ ├── index.ts # Server entry point — McpServer + stdio transport
│ ├── tools.ts # 15 MCP tool definitions with Zod schemas
│ └── obsidian.ts # Vault engine — direct filesystem operations
├── build/ # Compiled JS (generated by npm run build)
├── skills/ # MCP skills — copy these into other projects
│ ├── capture/SKILL.md
│ ├── find/SKILL.md
│ ├── log/SKILL.md
│ ├── note/SKILL.md
│ ├── review/SKILL.md
│ ├── standup/SKILL.md
│ ├── tidy/SKILL.md
│ └── today/SKILL.md
├── package.json
└── tsconfig.jsonTroubleshooting
Tools not appearing in Claude Code: Run claude mcp list to verify the server is registered. Check that the build path is correct.
Skills not appearing: Make sure the SKILL.md files are in the project's .claude/skills/<name>/SKILL.md directory structure. Claude Code auto-discovers skills from .claude/skills/.
"Vault not found" or "ENOENT" errors: Check that OBSIDIAN_VAULT points to a valid directory. The value should be the vault's folder path (e.g. /Users/you/Documents/My Vault). Verify with ls "$OBSIDIAN_VAULT".
File permission errors: The server needs read/write access to the vault directory. Check ownership and permissions on the vault folder.
Changes not appearing in Obsidian: The server writes directly to the filesystem. Obsidian's file watcher typically picks up changes within 1-2 seconds. If not, try switching to another note and back, or restarting Obsidian.
Rebuild after changes: If you edit source files, run npm run build. Claude Code loads the compiled JS from build/.
