# Reported issues for mcp-obsidian-cli

Pod holds 16 of 31 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [mcp-obsidian-cli](/mcp/mcp-obsidian-cli).

## Most discussed

### Smithery distribution: package as .mcpb bundle for stdio publishing

Smithery is an MCP catalog (smithery.ai) with two publishing paths:

- **URL** — for streamable-HTTP servers. Not applicable; this server is stdio.
- **Local (MCPB Bundle)** — for stdio servers. Smithery distributes a pre-built `.mcpb` bundle that clients download and run locally.

To list on Smithery, we need to ship an MCPB bundle.

### What MCPB requires

Per Anthropic's [Build a desktop extension with MCPB](https://github.com/anthropics/dxt) docs and the [MCPB spec](https://github.com/modelc

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/40) · 2026-05-17 · open · 2 comments

### README lede rewrite: lead with the Claude Desktop capture workflow

Source: "Grill resolutions (2026-05-21)" in `docs/ideas/discoverability-positioning.md`.

## What to build

Replace the implementation-first README opening (currently "MCP server that wraps the Obsidian CLI…") with a workflow-first lede aimed at the hero audience: **Claude Desktop users who want chat-to-vault capture.**

Hook: **"Start in Claude Desktop, not Obsidian."** Do your thinking in chat; when something's worth keeping, say "save this to my vault" and Claude lands it in the right place u

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/70) · 2026-05-22 · closed · 1 comment

### Vault switch: first verb call after vault=NAME change can return 'command not found' for an existing verb

## Found in
Wave 3 sniff test (PR #55 / #14), test T13.

## Symptom
After routing `vault=tyee` then cleaning up, the first `vault=scarp create path=... content=...` returned:

```
Error: Command "create" not found. Did you mean: base:create, templater:create-from-template?
```

But `vault=scarp help` immediately after lists `create`. Retrying the identical create command then succeeded. The scarp Obsidian window was not open when the test started — the first route appears to have opened/woken it

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/57) · 2026-05-20 · open · 1 comment

### obsidian_help: 'bases' doc slug unreachable — verb-wins collision swallows it

## Found in
Wave 3 sniff test (PR #55 / #14), test T3.

## Symptom
`obsidian_help({ topic: "bases" })` returns the live CLI verb help for `bases` (`bases — List all base files in vault`) instead of the Kepano Bases reference doc. The reference doc (comparison operators, filter/formula functions, view types, `.base` YAML example) is **unreachable** through `obsidian_help`.

## Cause
`bases` is both a live CLI verb AND a doc slug. The documented collision rule (`docs/briefs/deepen-architecture.md`

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/56) · 2026-05-20 · closed · 1 comment

### manifest parser over-collects English words as verbs under Discover

## What

Cosmetic. `obsidian_help()` no-arg returns a category-grouped verb index. Under the **Discover** category, capitalized English words like `Most`, `Quote`, `Use` appear as verb entries. They are not real verbs — the parser in \`lib/manifest.js\` is picking up sentence-leading words from \`obsidian help\` blurb text.

Surfaced during Gate C sniff test (T1, happy path).

## Expected

Verb index contains only real CLI verbs. Blurb prose is skipped.

## Likely cause

\`parseHelpOutput\` rege

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/53) · 2026-05-19 · open · 1 comment

### pass-through validation ordering when Obsidian is down

## What

Open question / likely bug. When Obsidian.app is not running:
- Pass-through call `obsidian({command: \"move dest=foo to=bar\"})` returns `EXECUTION_ERROR: The CLI is unable to find Obsidian` rather than the `dest=` → `to=` validation drift hint.

When Obsidian IS running (Gate C happy path):
- Same call correctly returns the validation hint *before* any CLI call.

## Expected

`manifest.validate(args)` is supposed to fire pre-CLI. The user is most likely to need a self-correctable hint

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/52) · 2026-05-19 · open · 1 comment

### obsidian_help: doc-slug topics gated by Obsidian liveness check

## What

When Obsidian.app is not running, calling `obsidian_help({topic: \"markdown\"})` (or any of the 4 doc-slug topics: `cli`, `markdown`, `bases`, `canvas`) returns:

```
EXECUTION_ERROR: The CLI is unable to find Obsidian. Please make sure Obsidian is running and try again.
```

Surfaced during Gate C sniff test (PR #50). Doc prompts are pure static text loaded from `./prompts/obsidian-*.md` — they should not require a running Obsidian instance.

## Expected

Doc-slug topics resolve to the

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/51) · 2026-05-19 · closed · 1 comment

### Add README demo asset (GIF) showing end-to-end vault interaction

Discoverability brief reserves a slot for a short demo asset in the README. Slot deferred from v1.3.3 metadata PR (`chore/discoverability`) — recording is content work, not metadata.

### Scope

- Record one tight flow (suggested: "ask AI to summarize today's daily note" or "search vault, append result to today").
- Format: GIF (renders on both GitHub and npmjs.com; asciinema does not render on npm).
- Path: `docs/demo.gif`.
- Reference from README near top, below badges and intro paragraph.

##

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/34) · 2026-05-17 · closed · 1 comment

## Most recent

### README recipes: 3-4 canonical Claude Desktop conversations

Source: "Grill resolutions (2026-05-21)" in `docs/ideas/discoverability-positioning.md`.

## What to build

Add a **Recipes** section to the README: 3-4 end-to-end Claude Desktop conversations (SEO bait + onboarding). Candidates:

- Research a topic and save findings as a project note
- Daily journal append from a conversation
- Find related notes and update one
- Pull project context into a new strategy doc

Each recipe shows the **actual chat phrasing** and **what lands in the vault**, coverin

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/73) · 2026-05-22 · open · 0 comments

### List in awesome-mcp-servers (top acquisition lever)

Source: "Grill resolutions (2026-05-21)" in `docs/ideas/discoverability-positioning.md`.

## What to build

Submit a PR adding `mcp-obsidian-cli` to the **awesome-mcp-servers** list. Per the grill, directories are the **acquisition lever** — repo-page views (8 uniq) prove installs come from snippet-copy in directories/blogs/Discord, not the README. The entry uses the final positive positioning (capture chat → Obsidian vault) and the new one-line description, in the correct category, following th

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/72) · 2026-05-22 · open · 0 comments

### Rewrite npm + registry description: lead with "Capture", keep keywords, fit registry byte ceiling

Source: "Grill resolutions (2026-05-21)" in `docs/ideas/discoverability-positioning.md`.

## What to build

Update the `package.json` `description` and the `server.json` registry description to **lead with the capture outcome** while keeping `obsidian` + `mcp` as the search terms people actually type. Direction:

> Capture chat notes to your Obsidian vault — MCP server via the official CLI: templates, daily notes, backlinks

The MCP Registry description has a **≤100-character ceiling — count BYT

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/71) · 2026-05-22 · closed · 0 comments

### Clarify OBSIDIAN_NOT_RUNNING message: backgrounded Obsidian is fine

## Context

The Discoverability positioning hook is **"start in Claude Desktop — no context-switch to Obsidian."** That pitch is honest only if users understand Obsidian still has to be **running** — it just doesn't need focus. A first-run user who reads "no need to open Obsidian" literally, has the app quit, and hits `OBSIDIAN_NOT_RUNNING`, bounces. That's a funnel leak on the hero path.

The current messages don't say *backgrounded/minimized is fine*:

- Runtime, per-tool-call: `server.js:88`

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/69) · 2026-05-22 · closed · 0 comments

### Discoverability: package metadata + README badges + MCP Registry refresh (v1.3.3)

Umbrella issue for the v1.3.3 discoverability push. Brief covers external-surface fixes plus a few metadata tweaks so the package is findable on npm, the MCP Registry, and community catalogs.

### Scope (single PR, branch `chore/discoverability`)

**package.json**
- Add `homepage` (`https://github.com/stonematt/mcp-obsidian-cli#readme`) and `bugs` (`https://github.com/stonematt/mcp-obsidian-cli/issues`)
- Rewrite description (94 chars, ≤100 limit): `Obsidian MCP server via the official CLI plugi

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/35) · 2026-05-17 · closed · 0 comments

### Docs drift: OBSIDIAN_CLI_PATH default disagrees across CLAUDE.md vs README/server.json/code

Project `CLAUDE.md` documents `OBSIDIAN_CLI_PATH` default as `obsidian`, but the actual default in `server.js`, `server.json`, and `README.md` is `obsidian-cli`.

### Sources

- `CLAUDE.md` (root) → `OBSIDIAN_CLI_PATH | obsidian | Path to CLI binary`
- `README.md` → `OBSIDIAN_CLI_PATH | obsidian-cli | Path to CLI binary`
- `server.json` → `"default": "obsidian-cli"`

### Resolution

Update `CLAUDE.md` to match the real default (`obsidian-cli`). Confirm code in `server.js` agrees, then close.

##

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/33) · 2026-05-17 · closed · 0 comments

### MCP resources for vault metadata (vault name, file count, tag list)

## Problem

The server exposes verbs as MCP tools but nothing as MCP resources. Clients that browse resources (Claude Desktop's resource picker, IDE integrations) have no read-only view of what vault they're connected to or what's in it. Discovery happens only after a tool call.

## Proposed change

Register MCP resources backed by the **ObsidianCli** + **VerbManifest** for:
- `obsidian://vault` — vault name and root path
- `obsidian://vault/files` — file count + sample listing
- `obsidian://vau

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/30) · 2026-05-17 · closed · 0 comments

### Structured output parsing — JSON CLI results as structured MCP content

## Problem

Today every CLI invocation returns its raw `stdout` wrapped in MCP `text` content. Several Obsidian CLI verbs support `format=json` (e.g. `properties`, `tasks`, `tags`, `files`, `search:context`) and emit machine-readable output, but clients receive it as a single string and must re-parse on their side.

## Proposed change

For verbs that support `format=json`:
- Pass `format=json` through the **ObsidianCli** when the **Typed tool** opts in.
- Parse the result and return it as struct

[Read the thread](https://github.com/stonematt/mcp-obsidian-cli/issues/29) · 2026-05-17 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/stonematt/mcp-obsidian-cli/issues).