mcp-obsidian Skill
The skill that makes AI use inside Obsidian effective. It operates notes and vaults through three surfaces (headless notesmd-cli, the app-backed official obsidian CLI, and the cyanheads MCP) and knows the two documented plugins (Iconic, Health.md) and the theme system at the file layer, so an agent can read, write, search, and extend what the vault contains without guessing.
1. WHEN TO USE
Activation Triggers (explicit user phrases)
- "obsidian", "obsidian vault", "notesmd-cli", "obsidian-mcp", "mcp-obsidian"
- "note", "notes", "markdown note", "daily note", "vault"
- "create a note", "open a note", "search notes", "search my vault"
- "add a tag to a note", "manage frontmatter", "delete a note", "move a note"
- "obsidian plugin"
- "health", "health data", "apple health", "health chart", "health-md", "health.md"
- "iconic", "icons", "icon color", "file icons", "folder icons", "icon rules", "iconic rulebook", "iconic ruleset", "iconic data json", "icon automation"
- "local rest api", "obsidian api key"
Automatic Triggers (keyword patterns)
notesmd-cli or obsidian (the CLI binary) appears in the request
obsidian + any action verb (create, open, search, list, print, move, delete, tag)
- "vault" in a note-management context
- "daily note" or "note frontmatter" in a personal-knowledge context
- MCP tool names:
obsidian_get_note, obsidian_write_note, obsidian_search_notes
When NOT to Use
- StevenStavrakis
obsidian-mcp — a different (filesystem-based) MCP server; this skill's MCP path uses the cyanheads obsidian-mcp-server. The Stavrakis server is documented only as the headless MCP alternative.
- Generic markdown authoring with no Obsidian vault — use
@markdown / sk-doc.
- Non-Obsidian note apps (Notion, Bear, Apple Notes) — wrong surface.
- Editing arbitrary repo files that merely happen to be markdown — use
Read/Edit directly.
2. SMART ROUTING
mcp-tooling routes an Obsidian vault or note request here when the request names Obsidian, a vault, notesmd-cli, the cyanheads MCP, or one of the two documented plugins.
The hub's mcp-obsidian mode signal selects this packet, and generic markdown authoring does not.
A scored route loads the documents its intent maps to. references/obsidian-cli-commands.md is the default resource, offered as a fallback suggestion and never loaded on a scored route.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Surface Comparison
| Dimension |
Headless CLI (notesmd-cli) |
App-backed CLI (obsidian) |
Cyanheads MCP |
| Activation |
notesmd-cli <command> in Bash |
obsidian <command> key=value in Bash |
Code Mode call_tool_chain() |
| Running app |
Not required — filesystem only |
Required, and NOT launched for you (exit 1 when down) |
Required + Local REST API |
| Best for |
Daily note ops anywhere |
In-app open / URI actions |
Structured reads/writes, tags, search |
| Auth |
None — reads the vault directory |
None — controls the local app |
OBSIDIAN_API_KEY bearer token |
| Install |
brew install yakitrak/yakitrak/notesmd-cli |
Ships with Obsidian desktop v1.12.4+ |
npx -y obsidian-mcp-server@latest |
| Config store |
~/.config/obsidian/obsidian.json |
In-app: Settings → Command line interface |
.utcp_config.json manual obsidian |
| Output |
Human-readable text |
Human-readable text on stdout, exit 0 even on failure |
Structured JSON |
Headless CLI — notesmd-cli (Default Path)
Yakitrak's notesmd-cli (binary notesmd-cli, renamed from "obsidian-cli" to avoid confusion with the official one) operates directly on the vault filesystem, so it works with no running app.
Step 1: Verify installation
notesmd-cli --version
notesmd-cli list-vaults # Shows registered vaults + default
Step 2: Install if missing
bash .skilled/skills/mcp-tooling/mcp-obsidian/scripts/install.sh
# or directly:
brew tap yakitrak/yakitrak && brew install yakitrak/yakitrak/notesmd-cli
Step 3: Register a vault (one-time)
notesmd-cli add-vault "/path/to/Vault" # writes ~/.config/obsidian/obsidian.json
notesmd-cli set-default-vault "Vault"
Step 4: Daily note operations
notesmd-cli list # List notes in the default vault
notesmd-cli search "meeting" # Search by note name
notesmd-cli search-content "action item" # Full-text content search
notesmd-cli print "Inbox" # Print a note to stdout
notesmd-cli create "New Idea" # Create a note
notesmd-cli daily # Open/append today's daily note
App-backed CLI — official obsidian (Live-App Path)
The official obsidian CLI shipped GA in Obsidian desktop v1.12.4 (Feb 2026). It is a remote control for an already-running app, not a headless tool and not a launcher: with the app down it prints The CLI is unable to find Obsidian to stderr and exits 1. There is no npm/brew package — it ships with the desktop app.
Enable in-app: Settings → General → Command line interface → toggle on → "Register CLI" (auto-adds obsidian to PATH on macOS/Linux; on macOS this symlinks /usr/local/bin/obsidian into the app bundle).
Syntax is obsidian <command> key=value, with no POSIX flags: obsidian version, not obsidian --version. Use it for outcomes only the live app can produce — the resolved link graph, the computed tag and task index, Bases queries, sync and file history, plugin and theme state, and in-app opens.
Two contracts before scripting it. Run obsidian version | grep -qE '^[0-9]+\.[0-9]+' before you script. A version number means the CLI is registered and the app is running. Exit 0 alone does not, because a starting app can return 0 with an error.
Then stop trusting $?. Once the app is up, the CLI exits 0 even on failure and prints Error: ... to stdout.
Both contracts, the 106-command surface and the active-file hazard are documented in references/official-cli-agent-usage.md.
Cyanheads MCP — obsidian-mcp-server (Structured Path)
The default MCP is cyanheads' obsidian-mcp-server (npm @3.5.0), launched over stdio via npx -y obsidian-mcp-server@latest (it also supports http on 127.0.0.1:3010/mcp). It talks to the vault through the Local REST API plugin v4.0.0+, so it needs a running Obsidian + the plugin enabled + an API key.
Prerequisites:
- Code Mode MCP configured, with the
obsidian manual in .utcp_config.json (not opencode.json, that file is for native/non-Code-Mode MCP tools)
- Obsidian running with the Local REST API plugin enabled and an API key generated
obsidian_OBSIDIAN_API_KEY (required), obsidian_OBSIDIAN_BASE_URL (default http://127.0.0.1:27123), obsidian_OBSIDIAN_VERIFY_SSL (default false) available to Code Mode
Configuration (.utcp_config.json, manual_call_templates):
{
"name": "obsidian",
"call_template_type": "mcp",
"config": {
"mcpServers": {
"obsidian": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "obsidian-mcp-server@latest"],
"env": {
"OBSIDIAN_API_KEY": "${obsidian_OBSIDIAN_API_KEY}",
"OBSIDIAN_BASE_URL": "${obsidian_OBSIDIAN_BASE_URL}",
"OBSIDIAN_VERIFY_SSL": "${obsidian_OBSIDIAN_VERIFY_SSL}"
}
}
}
}
}
The obsidian_ env prefix matches the manual name obsidian, so ${obsidian_OBSIDIAN_API_KEY} resolves correctly. This registration is already in place: the obsidian manual lives in .utcp_config.json and the obsidian_OBSIDIAN_* keys in .env.example. This skill documents that wiring; it does not rewrite those files.
Tools: the server exposes 14 obsidian_* tools. The core five are obsidian_get_note, obsidian_write_note, obsidian_search_notes, obsidian_manage_tags, obsidian_delete_note; the full 14-tool catalog with per-tool inputs lives in references/mcp-tools.md. Confirm every name with tool_info()/list_tools() before calling — never guess it from a description.
Invocation via Code Mode (call_tool_chain takes a single code string):
// Tool naming: obsidian.obsidian_{tool_name}
const result = await call_tool_chain({
code: `
const note = await obsidian.obsidian_get_note({ path: "Inbox/Idea.md" });
return note;
`,
});
When to prefer the MCP:
- Structured note reads/writes where you need JSON back, not terminal text
- Tag management (
obsidian_manage_tags) across a live vault
- Global or semantic search over an active, plugin-backed vault
Limitations:
- Requires a running Obsidian + Local REST API plugin + API key (headless CLI has none of these needs)
- Requires Code Mode MCP to be configured
OBSIDIAN_VERIFY_SSL defaults to false; only enable it behind a trusted TLS endpoint
Alternative MCP servers (two exist; do not conflate the tool names):
- Local REST API's own built-in MCP is served by the
obsidian-local-rest-api plugin (v5.1.0+). It exposes Streamable HTTP MCP at https://127.0.0.1:27124/mcp/ with 16 vault_* tools, including vault_read, vault_write, vault_patch, search_simple and tag_list.
This server is validated working and needs no extra npm package. It is a DIFFERENT surface from the cyanheads obsidian_* tools.
- StevenStavrakis'
obsidian-mcp (npm @1.0.6) is filesystem-based. Treat its no-app/no-token claim as VERIFY.
4. RULES
✅ ALWAYS
- Resolve the execution profile before acting — headless
notesmd-cli is the default; only route to the app-backed obsidian CLI or the MCP when a live app (and, for the MCP, Local REST API + OBSIDIAN_API_KEY) is actually available. Probe, do not assume.
- Register and confirm the vault first — run
notesmd-cli list-vaults and, if empty, notesmd-cli add-vault <path> + set-default-vault <name> before any note operation.
- Preview destructive note ops — for
move and delete, confirm the exact note name with notesmd-cli list / search before running the write; deletions are hard to reverse.
- Quote note names and paths — note titles and vault paths contain spaces; always wrap them in quotes in Bash.
- Run
notesmd-cli --version (and, for the MCP path, confirm the Local REST API is reachable) as preflight before starting an Obsidian session.
- Treat empty
notesmd-cli list / search results as valid — an empty vault or no-match search is not an error. Verify the default vault and query spelling before escalating.
- Confirm MCP tool names with
tool_info() before calling obsidian.obsidian_* — the callable form is obsidian.obsidian_{tool_name}.
⛔ NEVER
- Never assume a running app for the default path —
notesmd-cli is filesystem-only and needs no app; do not launch Obsidian just to run a headless note op.
- Never confuse the two CLIs —
notesmd-cli (Yakitrak, headless) and obsidian (official, app-backed) are different binaries with different behavior. The official one requires and controls a running app.
- Never use the StevenStavrakis
obsidian-mcp as the default MCP — this skill's MCP path is the cyanheads obsidian-mcp-server. The Stavrakis server is only the documented headless alternative.
- Never auto-modify
.utcp_config.json, .env.example, opencode.json, or hub files — the obsidian manual is already registered there; this skill only documents it. If the wiring ever needs changing, print the config for the user; never write these files programmatically.
- Never hardcode the API key or base URL in commands or notes — read them from
obsidian_OBSIDIAN_API_KEY / obsidian_OBSIDIAN_BASE_URL in the Code Mode environment.
- Never fabricate notes — if
notesmd-cli list/search returns empty, the vault or query is genuinely empty. Report it clearly.
- Never enable
OBSIDIAN_VERIFY_SSL blindly — it defaults to false; only turn it on behind a trusted TLS endpoint.
⚠️ ESCALATE IF
notesmd-cli is not installed and scripts/install.sh fails → report the OS/package-manager (brew/scoop/AUR) and Go toolchain state
notesmd-cli list-vaults shows no vault or no default → direct to add-vault + set-default-vault
- The MCP connection fails → verify the
obsidian manual in .utcp_config.json launches npx -y obsidian-mcp-server@latest over stdio, that Obsidian is running with Local REST API v4.0.0+ enabled, and that obsidian_OBSIDIAN_API_KEY / obsidian_OBSIDIAN_BASE_URL are set
- A
401/403 from the MCP → the API key is missing, wrong, or the Local REST API plugin is disabled
- A connection-refused / SSL error on
OBSIDIAN_BASE_URL → the plugin is not listening on the expected port, or OBSIDIAN_VERIFY_SSL is mismatched with the endpoint
5. SUCCESS CRITERIA
6. INTEGRATION POINTS
Gate 2 (Skill Routing): This skill activates at ≥0.8 confidence for Obsidian note/vault requests. The skill advisor matches on: obsidian, notesmd-cli, obsidian vault, note management, markdown notes, local rest api.
Code Mode MCP: The cyanheads MCP tools are invoked via mcp__code_mode__call_tool_chain. Tool naming convention: obsidian.obsidian_{tool_name}. See references/mcp-tools.md for the full 14-tool catalog.
Memory: Save Obsidian workflow context (default vault name, base URL, active plugin set) using /speckit:save when switching sessions.
Tool Usage: Use Bash for notesmd-cli and the official obsidian CLI. Use mcp__code_mode__call_tool_chain for cyanheads MCP operations. Use Read to load references on demand.
7. QUICK REFERENCE
notesmd-cli Command Cheat Sheet (headless)
| Category |
Command |
Description |
| Vaults |
notesmd-cli add-vault "<path>" |
Register a vault |
|
notesmd-cli remove-vault "<name>" |
Unregister a vault |
|
notesmd-cli list-vaults |
List registered vaults + default |
|
notesmd-cli set-default-vault "<name>" |
Set the default vault |
| Read |
notesmd-cli list |
List notes in the default vault |
|
notesmd-cli search "<query>" |
Search by note name |
|
notesmd-cli search-content "<query>" |
Full-text content search |
|
notesmd-cli print "<name>" |
Print a note to stdout |
| Write |
notesmd-cli create "<name>" |
Create a note |
|
notesmd-cli daily |
Open/append today's daily note |
|
notesmd-cli move "<a>" "<b>" |
Move / rename a note |
|
notesmd-cli delete "<name>" |
Delete a note |
|
notesmd-cli frontmatter "<name>" |
Edit a note's frontmatter |
| Open |
notesmd-cli open "<name>" |
Open a note |
Official obsidian CLI (app-backed)
Syntax is obsidian <command> key=value. No POSIX flags. Global option vault=<name>, accepted before or after the command.
| Command |
Description |
obsidian version |
Preflight. Exit 0 means registered AND app running; exit 1 means the app is down |
obsidian help |
The authoritative 106-command list from the installed binary |
obsidian read file="<name>" |
Print note content. Always pass a target, or it reads the human's open note |
obsidian create name="<name>" content="..." |
Create a note. On a name collision it makes <name> 1.md rather than failing |
obsidian append file="<name>" content="..." |
Append to a named note |
obsidian search query="..." format=json |
Search; JSON returns an array of paths |
obsidian search:context query="..." format=json |
Search with matching lines |
obsidian property:set file="<n>" name=k value=v |
Set a frontmatter property |
obsidian backlinks file="<name>" |
Resolved backlinks — no filesystem equivalent |
obsidian tags / obsidian tasks |
The app's computed vault-wide index |
obsidian base:query file="<base>" format=json |
Query a Base |
(Enable first: Settings → General → Command line interface → Register CLI. Ships with Obsidian desktop v1.12.4+. Every command above exits 0 even when it fails — check stdout for a leading Error:.)
Cyanheads MCP Call Pattern (Code Mode)
// Tool naming: obsidian.obsidian_{tool_name} — 14 tools total
await call_tool_chain({
code: `
const hit = await obsidian.obsidian_search_notes({ query: "roadmap" });
const note = await obsidian.obsidian_get_note({ path: hit[0].path });
await obsidian.obsidian_manage_tags({ path: hit[0].path, add: ["reviewed"] });
return note;
`,
});
8. REFERENCES AND RELATED RESOURCES
Reference Files (load on demand via router):
references/obsidian-cli-commands.md — Full notesmd-cli + official obsidian CLI command reference with agent patterns
references/official-cli-agent-usage.md — Official app-backed CLI: preflight, the exit-0 failure contract, key=value syntax, the 106-command surface, safety invariants, and where the vendor docs disagree with the binary
references/mcp-tools.md — Cyanheads obsidian-mcp-server 14-tool catalog, priorities, and call_tool_chain() invocation
references/troubleshooting.md — Install, vault, auth, Local REST API and MCP failures
references/notion-migration.md — Notion→Obsidian migration reconstruction method: 8-step method, division of labor, relation/rollup/formula recovery, comment reconstruction, verification protocol
references/plugins/plugin-operation-logic.md — How plugin-driven note automation is operated
references/plugins/iconic/iconic.md — Iconic icon/color rulebook plugin index (usage companion: assets/plugins/iconic/iconic-rules.full.md; canonical full rule payload: assets/plugins/iconic/iconic-rules.full.json, 21 file + 11 folder rules)
references/plugins/iconic/data-model.md — Iconic data.json keys, rule schema, and the merge-only rulebook contract
references/plugins/iconic/workflows.md — Iconic file-layer recipes: add/edit/disable rules, flip toggles, apply the canonical rulebook
references/plugins/iconic/troubleshooting.md — Iconic failure and recovery recipes
references/plugins/installed-plugins.md — Roster of all 24 enabled vault plugins in three classes: the two documented file-layer plugins, the thirteen file-layer plugins whose dedicated docs were removed, and the nine UI/automatic plugins that never had any
Install guide (front door): INSTALL-GUIDE.md — condensed top-level install doc for both CLI profiles and the MCP; references/troubleshooting.md is the router's INSTALL/TROUBLESHOOT-intent target.
Scripts:
scripts/install.sh — Installs notesmd-cli and prints the MCP config snippet
scripts/doctor.sh — Diagnoses the CLI + MCP setup, including a live obsidian version probe that separates "not registered" from "registered but the app is down"
Embedded Servers:
mcp-servers/obsidian-cli/README.md — notesmd-cli install pointer (brew/scoop/AUR/source); run setup.sh
mcp-servers/obsidian-mcp/README.md — Cyanheads obsidian-mcp-server configuration notes (stdio via npx -y obsidian-mcp-server@latest, OBSIDIAN_API_KEY/OBSIDIAN_BASE_URL/OBSIDIAN_VERIFY_SSL)
Examples:
examples/README.md — Guide to the example note-workflow scripts
examples/headless-notes-workflow.sh — notesmd-cli round trip with no running app
examples/official-cli-workflow.sh — Official app-backed CLI round trip with the preflight and the exit-0 result wrapper
Related Skills:
mcp-click-up — Structural sibling; same two-path (CLI + MCP) orchestrator pattern
mcp-code-mode — Code Mode MCP orchestration (used for cyanheads MCP invocation)
External:
1---2name: mcp-obsidian3description: Runs Obsidian vault and note work across notesmd-cli, the obsidian CLI and the cyanheads MCP, plus plugin and theme knowledge.4allowed-tools: [Bash, Edit, Glob, Grep, mcp__code_mode__call_tool_chain, Read, Write]5version: 0.24.7.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/mcp-obsidian8---910<!-- keywords: obsidian, obsidian vault, notesmd-cli, obsidian-mcp, note management, markdown notes, local rest api, health-md, health data, iconic, icon rules, iconic rulebook, icon automation, file icons, folder icons, iconic data json, iconic ruleset, iconic-rules.full.json, iconic-rules.full.md, data.json, obsidian theme, theme system, css theme, css snippet, css variables, theme development, plugin development -->1112# mcp-obsidian Skill1314The skill that makes AI use inside Obsidian effective. It operates notes and vaults through three surfaces (headless `notesmd-cli`, the app-backed official `obsidian` CLI, and the cyanheads MCP) and knows the two documented plugins (Iconic, Health.md) and the theme system at the file layer, so an agent can read, write, search, and extend what the vault contains without guessing.1516---1718## 1. WHEN TO USE1920### Activation Triggers (explicit user phrases)2122- "obsidian", "obsidian vault", "notesmd-cli", "obsidian-mcp", "mcp-obsidian"23- "note", "notes", "markdown note", "daily note", "vault"24- "create a note", "open a note", "search notes", "search my vault"25- "add a tag to a note", "manage frontmatter", "delete a note", "move a note"26- "obsidian plugin"27- "health", "health data", "apple health", "health chart", "health-md", "health.md"28- "iconic", "icons", "icon color", "file icons", "folder icons", "icon rules", "iconic rulebook", "iconic ruleset", "iconic data json", "icon automation"29- "local rest api", "obsidian api key"3031### Automatic Triggers (keyword patterns)3233- `notesmd-cli` or `obsidian` (the CLI binary) appears in the request34- `obsidian` + any action verb (create, open, search, list, print, move, delete, tag)35- "vault" in a note-management context36- "daily note" or "note frontmatter" in a personal-knowledge context37- MCP tool names: `obsidian_get_note`, `obsidian_write_note`, `obsidian_search_notes`3839### When NOT to Use4041- **StevenStavrakis `obsidian-mcp`** — a different (filesystem-based) MCP server; this skill's MCP path uses the cyanheads `obsidian-mcp-server`. The Stavrakis server is documented only as the headless MCP alternative.42- Generic markdown authoring with no Obsidian vault — use `@markdown` / `sk-doc`.43- Non-Obsidian note apps (Notion, Bear, Apple Notes) — wrong surface.44- Editing arbitrary repo files that merely happen to be markdown — use `Read`/`Edit` directly.4546---4748## 2. SMART ROUTING4950`mcp-tooling` routes an Obsidian vault or note request here when the request names Obsidian, a vault, `notesmd-cli`, the cyanheads MCP, or one of the two documented plugins.51The hub's `mcp-obsidian` mode signal selects this packet, and generic markdown authoring does not.5253A scored route loads the documents its intent maps to. `references/obsidian-cli-commands.md` is the default resource, offered as a fallback suggestion and never loaded on a scored route.5455Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.5657---5859## 3. HOW IT WORKS6061### Surface Comparison6263| Dimension | Headless CLI (`notesmd-cli`) | App-backed CLI (`obsidian`) | Cyanheads MCP |64|---|---|---|---|65| **Activation** | `notesmd-cli <command>` in Bash | `obsidian <command> key=value` in Bash | Code Mode `call_tool_chain()` |66| **Running app** | Not required — filesystem only | Required, and NOT launched for you (exit 1 when down) | Required + Local REST API |67| **Best for** | Daily note ops anywhere | In-app open / URI actions | Structured reads/writes, tags, search |68| **Auth** | None — reads the vault directory | None — controls the local app | `OBSIDIAN_API_KEY` bearer token |69| **Install** | `brew install yakitrak/yakitrak/notesmd-cli` | Ships with Obsidian desktop v1.12.4+ | `npx -y obsidian-mcp-server@latest` |70| **Config store** | `~/.config/obsidian/obsidian.json` | In-app: Settings → Command line interface | `.utcp_config.json` manual `obsidian` |71| **Output** | Human-readable text | Human-readable text on stdout, exit 0 even on failure | Structured JSON |7273### Headless CLI — `notesmd-cli` (Default Path)7475Yakitrak's `notesmd-cli` (binary `notesmd-cli`, renamed from "obsidian-cli" to avoid confusion with the official one) operates directly on the vault filesystem, so it works with **no running app**.7677**Step 1: Verify installation**78```bash79notesmd-cli --version80notesmd-cli list-vaults # Shows registered vaults + default81```8283**Step 2: Install if missing**84```bash85bash .skilled/skills/mcp-tooling/mcp-obsidian/scripts/install.sh86# or directly:87brew tap yakitrak/yakitrak && brew install yakitrak/yakitrak/notesmd-cli88```8990**Step 3: Register a vault (one-time)**91```bash92notesmd-cli add-vault "/path/to/Vault" # writes ~/.config/obsidian/obsidian.json93notesmd-cli set-default-vault "Vault"94```9596**Step 4: Daily note operations**97```bash98notesmd-cli list # List notes in the default vault99notesmd-cli search "meeting" # Search by note name100notesmd-cli search-content "action item" # Full-text content search101notesmd-cli print "Inbox" # Print a note to stdout102notesmd-cli create "New Idea" # Create a note103notesmd-cli daily # Open/append today's daily note104```105106### App-backed CLI — official `obsidian` (Live-App Path)107108The official `obsidian` CLI shipped GA in Obsidian desktop **v1.12.4** (Feb 2026). It is a **remote control for an already-running app**, not a headless tool and not a launcher: with the app down it prints `The CLI is unable to find Obsidian` to stderr and exits 1. There is no npm/brew package — it ships with the desktop app.109110**Enable in-app:** Settings → General → Command line interface → toggle on → "Register CLI" (auto-adds `obsidian` to PATH on macOS/Linux; on macOS this symlinks `/usr/local/bin/obsidian` into the app bundle).111112**Syntax is `obsidian <command> key=value`,** with no POSIX flags: `obsidian version`, not `obsidian --version`. Use it for outcomes only the live app can produce — the resolved link graph, the computed tag and task index, Bases queries, sync and file history, plugin and theme state, and in-app opens.113114**Two contracts before scripting it.** Run `obsidian version | grep -qE '^[0-9]+\.[0-9]+'` before you script. A version number means the CLI is registered and the app is running. Exit 0 alone does not, because a starting app can return 0 with an error.115Then stop trusting `$?`. Once the app is up, the CLI exits 0 even on failure and prints `Error: ...` to stdout.116Both contracts, the 106-command surface and the active-file hazard are documented in `references/official-cli-agent-usage.md`.117118### Cyanheads MCP — `obsidian-mcp-server` (Structured Path)119120The default MCP is cyanheads' `obsidian-mcp-server` (npm **@3.5.0**), launched over **stdio** via `npx -y obsidian-mcp-server@latest` (it also supports http on `127.0.0.1:3010/mcp`). It talks to the vault through the **Local REST API plugin v4.0.0+**, so it needs a **running Obsidian + the plugin enabled + an API key**.121122**Prerequisites:**123- Code Mode MCP configured, with the `obsidian` manual in `.utcp_config.json` (not `opencode.json`, that file is for native/non-Code-Mode MCP tools)124- Obsidian running with the Local REST API plugin enabled and an API key generated125- `obsidian_OBSIDIAN_API_KEY` (required), `obsidian_OBSIDIAN_BASE_URL` (default `http://127.0.0.1:27123`), `obsidian_OBSIDIAN_VERIFY_SSL` (default `false`) available to Code Mode126127**Configuration** (`.utcp_config.json`, `manual_call_templates`):128```json129{130 "name": "obsidian",131 "call_template_type": "mcp",132 "config": {133 "mcpServers": {134 "obsidian": {135 "transport": "stdio",136 "command": "npx",137 "args": ["-y", "obsidian-mcp-server@latest"],138 "env": {139 "OBSIDIAN_API_KEY": "${obsidian_OBSIDIAN_API_KEY}",140 "OBSIDIAN_BASE_URL": "${obsidian_OBSIDIAN_BASE_URL}",141 "OBSIDIAN_VERIFY_SSL": "${obsidian_OBSIDIAN_VERIFY_SSL}"142 }143 }144 }145 }146}147```148149The `obsidian_` env prefix matches the manual name `obsidian`, so `${obsidian_OBSIDIAN_API_KEY}` resolves correctly. This registration is already in place: the `obsidian` manual lives in `.utcp_config.json` and the `obsidian_OBSIDIAN_*` keys in `.env.example`. This skill documents that wiring; it does not rewrite those files.150151**Tools:** the server exposes **14 `obsidian_*` tools**. The core five are `obsidian_get_note`, `obsidian_write_note`, `obsidian_search_notes`, `obsidian_manage_tags`, `obsidian_delete_note`; the full 14-tool catalog with per-tool inputs lives in `references/mcp-tools.md`. Confirm every name with `tool_info()`/`list_tools()` before calling — never guess it from a description.152153**Invocation via Code Mode** (`call_tool_chain` takes a single `code` string):154```typescript155// Tool naming: obsidian.obsidian_{tool_name}156const result = await call_tool_chain({157 code: `158 const note = await obsidian.obsidian_get_note({ path: "Inbox/Idea.md" });159 return note;160 `,161});162```163164**When to prefer the MCP:**165- Structured note reads/writes where you need JSON back, not terminal text166- Tag management (`obsidian_manage_tags`) across a live vault167- Global or semantic search over an active, plugin-backed vault168169**Limitations:**170- Requires a running Obsidian + Local REST API plugin + API key (headless CLI has none of these needs)171- Requires Code Mode MCP to be configured172- `OBSIDIAN_VERIFY_SSL` defaults to `false`; only enable it behind a trusted TLS endpoint173174**Alternative MCP servers (two exist; do not conflate the tool names):**1751. **Local REST API's own built-in MCP** is served by the `obsidian-local-rest-api` plugin (v5.1.0+). It exposes Streamable HTTP MCP at `https://127.0.0.1:27124/mcp/` with 16 `vault_*` tools, including `vault_read`, `vault_write`, `vault_patch`, `search_simple` and `tag_list`.176 This server is validated working and needs no extra npm package. It is a DIFFERENT surface from the cyanheads `obsidian_*` tools.1772. **StevenStavrakis' `obsidian-mcp`** (npm @1.0.6) is filesystem-based. Treat its no-app/no-token claim as `VERIFY`.178179---180181## 4. RULES182183### ✅ ALWAYS1841851. **Resolve the execution profile before acting** — headless `notesmd-cli` is the default; only route to the app-backed `obsidian` CLI or the MCP when a live app (and, for the MCP, Local REST API + `OBSIDIAN_API_KEY`) is actually available. Probe, do not assume.1862. **Register and confirm the vault first** — run `notesmd-cli list-vaults` and, if empty, `notesmd-cli add-vault <path>` + `set-default-vault <name>` before any note operation.1873. **Preview destructive note ops** — for `move` and `delete`, confirm the exact note name with `notesmd-cli list` / `search` before running the write; deletions are hard to reverse.1884. **Quote note names and paths** — note titles and vault paths contain spaces; always wrap them in quotes in Bash.1895. **Run `notesmd-cli --version` (and, for the MCP path, confirm the Local REST API is reachable) as preflight** before starting an Obsidian session.1906. **Treat empty `notesmd-cli list` / `search` results as valid** — an empty vault or no-match search is not an error. Verify the default vault and query spelling before escalating.1917. **Confirm MCP tool names with `tool_info()`** before calling `obsidian.obsidian_*` — the callable form is `obsidian.obsidian_{tool_name}`.192193### ⛔ NEVER1941951. **Never assume a running app for the default path** — `notesmd-cli` is filesystem-only and needs no app; do not launch Obsidian just to run a headless note op.1962. **Never confuse the two CLIs** — `notesmd-cli` (Yakitrak, headless) and `obsidian` (official, app-backed) are different binaries with different behavior. The official one requires and controls a running app.1973. **Never use the StevenStavrakis `obsidian-mcp` as the default MCP** — this skill's MCP path is the cyanheads `obsidian-mcp-server`. The Stavrakis server is only the documented headless alternative.1984. **Never auto-modify `.utcp_config.json`, `.env.example`, `opencode.json`, or hub files** — the `obsidian` manual is already registered there; this skill only documents it. If the wiring ever needs changing, print the config for the user; never write these files programmatically.1995. **Never hardcode the API key or base URL in commands or notes** — read them from `obsidian_OBSIDIAN_API_KEY` / `obsidian_OBSIDIAN_BASE_URL` in the Code Mode environment.2006. **Never fabricate notes** — if `notesmd-cli list`/`search` returns empty, the vault or query is genuinely empty. Report it clearly.2017. **Never enable `OBSIDIAN_VERIFY_SSL` blindly** — it defaults to `false`; only turn it on behind a trusted TLS endpoint.202203### ⚠️ ESCALATE IF204205- `notesmd-cli` is not installed and `scripts/install.sh` fails → report the OS/package-manager (brew/scoop/AUR) and Go toolchain state206- `notesmd-cli list-vaults` shows no vault or no default → direct to `add-vault` + `set-default-vault`207- The MCP connection fails → verify the `obsidian` manual in `.utcp_config.json` launches `npx -y obsidian-mcp-server@latest` over stdio, that Obsidian is running with Local REST API v4.0.0+ enabled, and that `obsidian_OBSIDIAN_API_KEY` / `obsidian_OBSIDIAN_BASE_URL` are set208- A `401`/`403` from the MCP → the API key is missing, wrong, or the Local REST API plugin is disabled209- A connection-refused / SSL error on `OBSIDIAN_BASE_URL` → the plugin is not listening on the expected port, or `OBSIDIAN_VERIFY_SSL` is mismatched with the endpoint210211---212213## 5. SUCCESS CRITERIA214215- [ ] `notesmd-cli --version` prints a version string216- [ ] `notesmd-cli list-vaults` shows at least one registered vault with a default217- [ ] `notesmd-cli list` returns notes for the default vault (empty list is valid)218- [ ] `notesmd-cli search-content "<query>"` returns body matches (title `search` is broken in v0.3.6 — use `list` + filter for names)219- [ ] For app-backed work: `obsidian version` exits 0 before any other official-CLI call, and each result is checked for a leading `Error:` on stdout rather than by exit status220- [ ] For MCP work: a Code Mode `obsidian.obsidian_get_note` call returns note content as JSON221222---223224## 6. INTEGRATION POINTS225226**Gate 2 (Skill Routing):** This skill activates at ≥0.8 confidence for Obsidian note/vault requests. The skill advisor matches on: `obsidian`, `notesmd-cli`, `obsidian vault`, `note management`, `markdown notes`, `local rest api`.227228**Code Mode MCP:** The cyanheads MCP tools are invoked via `mcp__code_mode__call_tool_chain`. Tool naming convention: `obsidian.obsidian_{tool_name}`. See `references/mcp-tools.md` for the full 14-tool catalog.229230**Memory:** Save Obsidian workflow context (default vault name, base URL, active plugin set) using `/speckit:save` when switching sessions.231232**Tool Usage:** Use Bash for `notesmd-cli` and the official `obsidian` CLI. Use `mcp__code_mode__call_tool_chain` for cyanheads MCP operations. Use Read to load references on demand.233234---235236## 7. QUICK REFERENCE237238### notesmd-cli Command Cheat Sheet (headless)239240| Category | Command | Description |241|---|---|---|242| **Vaults** | `notesmd-cli add-vault "<path>"` | Register a vault |243| | `notesmd-cli remove-vault "<name>"` | Unregister a vault |244| | `notesmd-cli list-vaults` | List registered vaults + default |245| | `notesmd-cli set-default-vault "<name>"` | Set the default vault |246| **Read** | `notesmd-cli list` | List notes in the default vault |247| | `notesmd-cli search "<query>"` | Search by note name |248| | `notesmd-cli search-content "<query>"` | Full-text content search |249| | `notesmd-cli print "<name>"` | Print a note to stdout |250| **Write** | `notesmd-cli create "<name>"` | Create a note |251| | `notesmd-cli daily` | Open/append today's daily note |252| | `notesmd-cli move "<a>" "<b>"` | Move / rename a note |253| | `notesmd-cli delete "<name>"` | Delete a note |254| | `notesmd-cli frontmatter "<name>"` | Edit a note's frontmatter |255| **Open** | `notesmd-cli open "<name>"` | Open a note |256257### Official `obsidian` CLI (app-backed)258259Syntax is `obsidian <command> key=value`. No POSIX flags. Global option `vault=<name>`, accepted before or after the command.260261| Command | Description |262|---|---|263| `obsidian version` | Preflight. Exit 0 means registered AND app running; exit 1 means the app is down |264| `obsidian help` | The authoritative 106-command list from the installed binary |265| `obsidian read file="<name>"` | Print note content. **Always pass a target**, or it reads the human's open note |266| `obsidian create name="<name>" content="..."` | Create a note. On a name collision it makes `<name> 1.md` rather than failing |267| `obsidian append file="<name>" content="..."` | Append to a named note |268| `obsidian search query="..." format=json` | Search; JSON returns an array of paths |269| `obsidian search:context query="..." format=json` | Search with matching lines |270| `obsidian property:set file="<n>" name=k value=v` | Set a frontmatter property |271| `obsidian backlinks file="<name>"` | Resolved backlinks — no filesystem equivalent |272| `obsidian tags` / `obsidian tasks` | The app's computed vault-wide index |273| `obsidian base:query file="<base>" format=json` | Query a Base |274275*(Enable first: Settings → General → Command line interface → Register CLI. Ships with Obsidian desktop v1.12.4+. Every command above exits 0 even when it fails — check stdout for a leading `Error:`.)*276277### Cyanheads MCP Call Pattern (Code Mode)278279```typescript280// Tool naming: obsidian.obsidian_{tool_name} — 14 tools total281await call_tool_chain({282 code: `283 const hit = await obsidian.obsidian_search_notes({ query: "roadmap" });284 const note = await obsidian.obsidian_get_note({ path: hit[0].path });285 await obsidian.obsidian_manage_tags({ path: hit[0].path, add: ["reviewed"] });286 return note;287 `,288});289```290291---292293## 8. REFERENCES AND RELATED RESOURCES294295**Reference Files (load on demand via router):**296- `references/obsidian-cli-commands.md` — Full `notesmd-cli` + official `obsidian` CLI command reference with agent patterns297- `references/official-cli-agent-usage.md` — Official app-backed CLI: preflight, the exit-0 failure contract, `key=value` syntax, the 106-command surface, safety invariants, and where the vendor docs disagree with the binary298- `references/mcp-tools.md` — Cyanheads `obsidian-mcp-server` 14-tool catalog, priorities, and `call_tool_chain()` invocation299- `references/troubleshooting.md` — Install, vault, auth, Local REST API and MCP failures300- `references/notion-migration.md` — Notion→Obsidian migration reconstruction method: 8-step method, division of labor, relation/rollup/formula recovery, comment reconstruction, verification protocol301- `references/plugins/plugin-operation-logic.md` — How plugin-driven note automation is operated302- `references/plugins/iconic/iconic.md` — Iconic icon/color rulebook plugin index (usage companion: `assets/plugins/iconic/iconic-rules.full.md`; canonical full rule payload: `assets/plugins/iconic/iconic-rules.full.json`, 21 file + 11 folder rules)303- `references/plugins/iconic/data-model.md` — Iconic `data.json` keys, rule schema, and the merge-only rulebook contract304- `references/plugins/iconic/workflows.md` — Iconic file-layer recipes: add/edit/disable rules, flip toggles, apply the canonical rulebook305- `references/plugins/iconic/troubleshooting.md` — Iconic failure and recovery recipes306- `references/plugins/installed-plugins.md` — Roster of all 24 enabled vault plugins in three classes: the two documented file-layer plugins, the thirteen file-layer plugins whose dedicated docs were removed, and the nine UI/automatic plugins that never had any307308Install guide (front door): [INSTALL-GUIDE.md](INSTALL-GUIDE.md) — condensed top-level install doc for both CLI profiles and the MCP; `references/troubleshooting.md` is the router's INSTALL/TROUBLESHOOT-intent target.309310**Scripts:**311- `scripts/install.sh` — Installs `notesmd-cli` and prints the MCP config snippet312- `scripts/doctor.sh` — Diagnoses the CLI + MCP setup, including a live `obsidian version` probe that separates "not registered" from "registered but the app is down"313314**Embedded Servers:**315- `mcp-servers/obsidian-cli/README.md` — `notesmd-cli` install pointer (brew/scoop/AUR/source); run `setup.sh`316- `mcp-servers/obsidian-mcp/README.md` — Cyanheads `obsidian-mcp-server` configuration notes (stdio via `npx -y obsidian-mcp-server@latest`, `OBSIDIAN_API_KEY`/`OBSIDIAN_BASE_URL`/`OBSIDIAN_VERIFY_SSL`)317318**Examples:**319- `examples/README.md` — Guide to the example note-workflow scripts320- `examples/headless-notes-workflow.sh` — `notesmd-cli` round trip with no running app321- `examples/official-cli-workflow.sh` — Official app-backed CLI round trip with the preflight and the exit-0 result wrapper322323**Related Skills:**324- `mcp-click-up` — Structural sibling; same two-path (CLI + MCP) orchestrator pattern325- `mcp-code-mode` — Code Mode MCP orchestration (used for cyanheads MCP invocation)326327**External:**328- notesmd-cli repository: [Yakitrak/obsidian-cli](https://github.com/Yakitrak/obsidian-cli)329- cyanheads obsidian-mcp-server: [cyanheads/obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server)330- Obsidian Local REST API plugin: [obsidian-local-rest-api](https://github.com/coddingtonbear/obsidian-local-rest-api)