home / skills / zpankz / mcp-skillset / obsidian-devtools

obsidian-devtools skill

safe

This skill lets you inspect and automate Obsidian using Chrome DevTools Protocol to read state, execute code, and debug plugins.

npx playbooks add skill zpankz/mcp-skillset --skill obsidian-devtools

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: obsidian-devtools
description: Inspect and automate Obsidian using Chrome DevTools Protocol
tools:
  - obsidian_launch_debug
  - obsidian_eval
  - obsidian_inspect_dom
  - obsidian_read_console
---

# Obsidian DevTools Skill

Enables deep inspection of the Obsidian application state via the Chrome DevTools Protocol.

## Capabilities
- Execute arbitrary JavaScript in the Obsidian context (`app.vault.getFiles()`)
- Read console logs for debugging plugins
- Inspect the DOM to understand UI state

## Setup
This skill requires the `obsidian-devtools` MCP server to be running or available.
The tools usually auto-launch Obsidian with `--remote-debugging-port=9222`.

## Tools

### `obsidian_launch_debug`
Launches or connects to Obsidian with remote debugging enabled.
- `restart`: (bool) Force restart Obsidian to enable debugging (default: False)

### `obsidian_eval`
Executes JavaScript code in the Obsidian app context.
- `expression`: (str) JavaScript code to run
- `await_promise`: (bool) Wait for promises to resolve (default: True)

### `obsidian_inspect_dom`
Gets a simplified snapshot of the DOM structure.
- `selector`: (str) CSS selector for root element (default: "body")

### `obsidian_read_console`
(Experimental) Reads console logs. Currently requires persistent listener mode.

## Examples

**Get Vault Name:**
```javascript
app.vault.getName()
```

**List Plugins:**
```javascript
Object.keys(app.plugins.manifests)
```

**Get Active File:**
```javascript
app.workspace.getActiveFile()?.path
```

Overview

This skill inspects and automates the Obsidian desktop app using the Chrome DevTools Protocol. It connects to or launches Obsidian with remote debugging enabled and exposes tools to run JavaScript inside the app, read console output, and capture DOM snapshots. It is designed for plugin authors, power users, and testers who need programmatic access to Obsidian internals. The skill requires a running obsidian-devtools MCP server or the app started with remote debugging enabled.

How this skill works

The skill connects to Obsidian's DevTools endpoint (typically via --remote-debugging-port) and executes commands over the Chrome DevTools Protocol. It can evaluate arbitrary JavaScript expressions in the Obsidian renderer context, capture simplified DOM trees from a selector, and read console logs when a persistent listener is active. Tools include a launcher/connector that can restart Obsidian for debugging, an evaluator that can await promises, a DOM inspector, and a console reader.

When to use it

Debugging or developing Obsidian plugins by executing app-level JavaScript and inspecting plugin manifests.
Automating inspection tasks like listing vault files, querying the active file, or sampling app state programmatically.
Capturing the UI structure or element hierarchy without manual inspection to reproduce visual or layout issues.
Collecting console logs from the Obsidian renderer for diagnosing runtime errors or plugin warnings.
Running integration tests that need to interact with the live Obsidian app context.
Rapidly prototyping scripts that rely on app.vault or app.workspace APIs.

Best practices

Run the obsidian-devtools MCP server and ensure Obsidian is started with a known remote debugging port before connecting.
Use obsidian_eval with await_promise=true for operations that return promises (file reads, plugin init hooks).
Limit DOM inspection to a specific selector to reduce payload size and speed up snapshots.
Avoid executing untrusted code; evaluating arbitrary JavaScript runs inside the user’s app context.
Enable persistent console listening only when necessary to reduce resource use and noise.

Example use cases

List all installed plugin IDs via Object.keys(app.plugins.manifests) to audit enabled extensions.
Retrieve the current active note path with app.workspace.getActiveFile()?.path for automation workflows.
Fetch the vault file list using app.vault.getFiles() for batch processing or metadata extraction.
Capture a DOM snapshot of the note view to diagnose rendering or CSS conflicts introduced by a theme.
Stream console logs while reproducing a bug to capture plugin stack traces and warnings.

FAQ

Do I need to start Obsidian manually with a flag?

The skill can launch or connect; however, remote debugging must be enabled (commonly via --remote-debugging-port). The obsidian_launch_debug tool can restart Obsidian to ensure debugging is active.

Can I run asynchronous Obsidian APIs?

Yes. Use obsidian_eval with await_promise set to true to wait for promises returned by app APIs.