live-mcp-for-obsidian

A live connection between AI assistants and your running Obsidian instance.

Important

Disclaimer: This project is not created by, affiliated with, or endorsed by Obsidian or Dynalist Inc. "Obsidian" is a trademark of Dynalist Inc. This project uses Obsidian's native CLI interface for interoperability.

Most Obsidian MCP servers treat your vault as a folder of files — read, write, search. This one connects to the live application. It can read your notes, but it can also click buttons, manage plugins, take screenshots, execute JavaScript, inspect the DOM, emulate mobile, record video of the UI, and control the full Obsidian UI. 46 tools, zero plugins required.

Demo

demo-3.mp4

More demos

How is this different?

There are 20+ Obsidian MCP servers in the community. Nearly all of them do the same thing: expose vault files over HTTP or stdio so an AI can read and write markdown.

This server operates at a fundamentally different level:

	File-based MCP servers	live-mcp-for-obsidian
Read/write notes	Yes	Yes
Search vault	Yes	Yes
Interact with plugins	No	Yes — enable, disable, reload, inspect
Click UI elements	No	Yes — any button, menu, or control
Take screenshots	No	Yes — full window or targeted element
Execute JavaScript	No	Yes — full app.* API access
Inspect DOM/CSS	No	Yes — like Chrome DevTools
Mobile emulation	No	Yes — test mobile layouts
Console/error capture	No	Yes — live debugging
Requires Obsidian plugins	Usually	No — uses native CLI

It's the difference between a file server and full app automation.

Remote access

With SSH access to the machine running Obsidian, you get full remote control — every tool works over an SSH session. No HTTP server, no OAuth, no Cloudflare Tunnel, no Tailscale. Just SSH in, run Claude Code, and you have a live connection to your Obsidian instance from anywhere.

Requirements

• Obsidian 1.12.4+ (with CLI support)
• Node.js 18+
• macOS (Linux/Windows: adjust the Obsidian binary path)
• ffmpeg — only for the three screen recording tools. Everything else works without it. Install with brew install ffmpeg.

Install

Claude Code

claude mcp add obsidian-live -- npx live-mcp-for-obsidian

With a specific vault:

claude mcp add obsidian-live -- npx live-mcp-for-obsidian --vault "My Vault"

This registers the server in your user-level config (~/.claude.json), making it available in every Claude Code session on your machine. To limit it to a single project, add --scope project which writes to .mcp.json in the current directory instead.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-live": {
      "command": "npx",
      "args": ["live-mcp-for-obsidian"]
    }
  }
}

With a specific vault:

{
  "mcpServers": {
    "obsidian-live": {
      "command": "npx",
      "args": ["live-mcp-for-obsidian", "--vault", "My Vault"]
    }
  }
}

From source

git clone https://github.com/gapmiss/live-mcp-for-obsidian.git
cd live-mcp-for-obsidian
npm install
npm run build
claude mcp add obsidian-live -- node ./build/cli.js

CLI Options

Flag	Default	Description
--obsidian-path	/Applications/Obsidian.app/Contents/MacOS/Obsidian	Path to Obsidian binary
--vault, -v	Active vault	Target a specific vault by name

What can it do?

Vault management

"What files are in my Projects folder?" "Create a new note called 'Meeting Notes' with a template" "Move all files from Inbox/ to Archive/" "Show me orphaned notes with no backlinks" "What are my incomplete tasks across the vault?"

Daily notes

"Read my daily note" "Append '- Called dentist to reschedule' to today's daily note" "What tasks are on today's daily note?"

Session briefing

"Give me a briefing"

One call to obsidian_briefing returns the active file, open tabs, daily note status, recent files, vault stats, and any persistent instructions from a CLAUDE.md file in your vault root. Instant situational awareness — no setup, no storage, ~300 tokens.

Live UI automation

"Click the p2p-share status bar item and select 'Pair with device'" "Toggle the theme mode button" "Open the command palette and run 'Graph view: Open local graph'"

The assistant can interact with any UI element via obsidian_eval — clicking buttons, opening menus, filling inputs, navigating the interface. Anything you can do with a mouse, the assistant can do programmatically.

Plugin development

"Reload my plugin so I can test the changes" "What commands does my plugin register?" "Take a screenshot of .my-plugin-settings so I can see how my settings tab looks" "Show me the console errors after I triggered that bug" "What CSS is applied to .my-plugin-container?" "Toggle mobile emulation so I can test the mobile layout"

Full Chrome DevTools capabilities — DOM inspection, CSS debugging, console/error capture, screenshots, and arbitrary JS evaluation — plus Obsidian-specific tools like plugin reload and command listing.

Screenshots

"Take a screenshot" "Screenshot just the .workspace-leaf.mod-active element" "Take a jpeg screenshot at 80% quality" "Screenshot the sidebar: .workspace-split.mod-left-split"

obsidian_screenshot uses Chrome DevTools Protocol for capture, supporting full-window or element-targeted screenshots via CSS selector. Choose between png, jpeg, or webp output, and control compression quality for jpeg/webp. Element targeting finds the first visible match — useful in Obsidian where multiple hidden duplicates of a selector may exist.

Theme development

"What CSS variables does the current theme define for text colors?" "Inspect the computed styles on the sidebar" "Screenshot the .workspace-leaf-content, then switch to dark mode and take another" "Show me the CSS source locations for .workspace-leaf"

Knowledge base queries

"List all tags sorted by frequency" "What properties does this note have?" "Show me the outline of my 'Architecture' note" "What notes link to 'Project Alpha'?" "Find all unresolved links in my vault"

Automation

"Execute the 'daily-notes:open' command" "Disable the 'calendar' plugin" "Set the 'status' property to 'done' on this note" "Enable the minimal theme"

The obsidian_command tool can trigger any registered command, and obsidian_eval can run arbitrary JavaScript for anything not covered by a dedicated tool.

Tools Reference

Status & Vaults

Tool	Description
obsidian_status	Get Obsidian version, vault name, path, file/folder counts, and size
obsidian_vaults	List all known vaults

Workspace

Tool	Description
obsidian_tabs	List all open tabs with their view type
obsidian_workspace	Show the workspace tree layout
obsidian_open	Open a file in Obsidian

Files & Vault

Tool	Description
obsidian_files	List files, optionally filtered by folder or extension
obsidian_read	Read the contents of a file
obsidian_create	Create a new file in the vault
obsidian_append	Append content to a file
obsidian_prepend	Prepend content to a file
obsidian_delete	Delete a file (moves to trash by default)
obsidian_move	Move or rename a file
obsidian_search	Search files, tags, properties, or links in the vault

Notes & Metadata

Tool	Description
obsidian_properties	List properties in the vault or for a specific file
obsidian_property_set	Set a property on a file
obsidian_tags	List tags in the vault or for a specific file
obsidian_links	List outgoing links from a file
obsidian_backlinks	List backlinks to a file
obsidian_outline	Show headings for a file
obsidian_tasks	List tasks in the vault or a specific file
obsidian_daily	Open or read the daily note
obsidian_daily_append	Append content to the daily note

Plugins & Commands

Tool	Description
obsidian_plugins	List installed plugins with enabled/disabled state
obsidian_plugin_info	Get detailed info about a specific plugin
obsidian_plugin_enable	Enable a plugin
obsidian_plugin_disable	Disable a plugin
obsidian_plugin_reload	Reload a plugin (useful during development)
obsidian_commands	List available commands, optionally filtered by prefix
obsidian_command	Execute an Obsidian command by ID

Themes & Appearance

Tool	Description
obsidian_theme	Show active theme info or get details about a specific theme
obsidian_themes	List installed themes
obsidian_snippets	List installed CSS snippets

Developer Tools

Tool	Description
obsidian_eval	Execute JavaScript in Obsidian and return the result
obsidian_dom	Query DOM elements by CSS selector
obsidian_console	Show captured console messages
obsidian_errors	Show captured errors
obsidian_screenshot	Take a screenshot of the full window or a specific element via CSS selector. Supports png/jpeg/webp output and quality control.
obsidian_css	Inspect CSS with source locations for a selector
obsidian_cdp	Run a Chrome DevTools Protocol command directly
obsidian_debug	Attach or detach the CDP debugger
obsidian_mobile	Toggle mobile emulation on or off
obsidian_devtools	Toggle Electron DevTools open/closed

Memory

Tool	Description
obsidian_briefing	Snapshot of current state: active file, tabs, daily note, recent files, vault stats, CLAUDE.md

Screen Recording

Records video of the Obsidian window by capturing frames over the Chrome DevTools Protocol, then encoding them with ffmpeg. Requires ffmpeg on your PATH.

Tool	Description
obsidian_record	Record for a fixed duration (1-120 seconds) and encode. One call, blocks until finished.
obsidian_start_recording	Begin an open-ended recording. Returns a session ID.
obsidian_stop_recording	Stop a session by ID and encode the captured frames. Returns the output file path.

Both paths accept fps (1-15, default 5) and format (mp4, webm, or gif, default mp4). Use obsidian_record when you know the length in advance; use the start/stop pair when the recording needs to span other tool calls, such as capturing a UI action while you drive it.

obsidian_record blocks for the full duration you request. If your MCP client has a request timeout shorter than that, a long recording will appear to fail even though it completes. Use obsidian_start_recording and obsidian_stop_recording instead for anything long.

Frames that fail to capture are skipped rather than aborting the recording, so a busy or unresponsive Obsidian window produces a shorter video rather than an error. Both stop paths return an error if zero frames were captured.

How It Works

This server is a thin MCP wrapper around Obsidian's native CLI. Each tool maps to one or more CLI commands:

obsidian_read { file: "My Note" }
  → obsidian read file="My Note"

obsidian_plugin_reload { id: "my-plugin" }
  → obsidian plugin:reload id=my-plugin

obsidian_dom { selector: ".workspace-leaf", text: true }
  → obsidian dev:dom selector=".workspace-leaf" text

obsidian_screenshot { selector: ".workspace-leaf", format: "jpeg", quality: 80 }
  → CDP Page.captureScreenshot with element clip region

No network servers, no ports, no plugins to install. The CLI communicates with the running Obsidian instance directly.

Token usage

Every MCP tool call consumes tokens — the tool description, the input parameters, and the response all count. This server is designed to be lightweight: most responses are raw CLI output with no wrapper text, and write operations return single-word confirmations like "Created" or "Deleted" (1-4 tokens).

What a typical session looks like

Action	Tool calls	Typical tokens
Session briefing	1 (obsidian_briefing)	100-400
Read a note	1 (obsidian_read)	50-2,000+ (depends on note length)
Append to daily note	1 (obsidian_daily_append)	~30 (input + "Appended to daily note")
Take a screenshot	1 (obsidian_screenshot)	~30 (returns only a file path)
Enable a plugin	1 (obsidian_plugin_enable)	~20 (returns "Enabled")
List vault files	1 (obsidian_files)	50-5,000+ (depends on vault size)

Most interactions are small. A "read my daily note and append a task" flow is ~3 tool calls and a few hundred tokens total. The expensive operations are the ones that return large, unbounded content.

Tools with large outputs

These tools can return substantial output depending on your vault size and content:

Tool	What drives size	How to reduce it
obsidian_files	Number of files in vault	Use folder, ext filters, or total: true for count only
obsidian_read	Length of the note	No built-in limit — large notes return in full
obsidian_tasks	Number of tasks vault-wide	Use file, path, active, daily, or done/todo filters
obsidian_commands	Number of installed plugins	Use filter to match by command ID prefix
obsidian_dom	DOM complexity	Avoid all: true on broad selectors; use text: true for text-only
obsidian_eval / obsidian_cdp	Whatever your code returns	Design your code to return only what you need
obsidian_briefing	CLAUDE.md file size	Keep your vault's CLAUDE.md concise

Built-in efficiency features

Several tools include parameters specifically for reducing output:

• total: true on obsidian_files, obsidian_links, obsidian_backlinks — returns only a count instead of the full list
• format on obsidian_tags, obsidian_tasks, obsidian_properties, obsidian_plugins, obsidian_backlinks — choose tsv or csv for compact tabular output, json for structured data
• filter on obsidian_plugins (by type), obsidian_commands (by ID prefix) — narrow results before they're returned
• done / todo on obsidian_tasks — get only completed or incomplete tasks
• active / daily on obsidian_tasks, obsidian_tags, obsidian_properties — scope to current file or daily note instead of full vault
• text: true on obsidian_dom — return text content instead of raw HTML
• limit on obsidian_console — cap the number of console messages returned

Tips for keeping token usage low

1. Start with obsidian_briefing — one call gives you active file, open tabs, daily note status, recent files, and vault stats. Much cheaper than calling each tool separately.
2. Use filters on list tools — obsidian_files with ext=md and folder=Projects is dramatically cheaper than listing the entire vault.
3. Prefer total: true when you only need a count — "how many markdown files?" costs ~20 tokens instead of listing thousands of paths.
4. Scope tasks and tags to a file — vault-wide obsidian_tasks on a large vault can be expensive; obsidian_tasks with active: true is not.
5. Use text: true with obsidian_dom — raw HTML is verbose; text content is usually what you need.
6. Keep your vault's CLAUDE.md short — obsidian_briefing includes it in full. A few focused lines is better than a wall of text.

FAQ

Is this safe? This server runs locally and communicates only via stdio — there's no network exposure. Destructive tools like obsidian_delete require confirmation from your MCP client before executing. See SECURITY.md for the full trust model.

Why does it need obsidian_eval? Obsidian has 800+ API methods. 42 tools cover the common operations. Eval is the escape hatch for everything else — and it's what makes use cases like "click that button" or "check the graph view" possible.

What if I don't want the powerful tools? Your MCP client controls which tool calls are approved. Claude Code and Claude Desktop both show you the tool call and its arguments before executing. You can deny any call you're not comfortable with.

Security

This server executes commands against a running Obsidian instance. Tools like obsidian_eval and obsidian_cdp are powerful by design — they provide full JavaScript execution and DevTools access for app automation.

See SECURITY.md for the full trust model, input handling details, and security considerations.

Disclaimer

This project is not created by, affiliated with, or endorsed by Obsidian or Dynalist Inc. "Obsidian" is a trademark of Dynalist Inc. This project uses Obsidian's native CLI interface for interoperability purposes only.

License

MIT