create_note
Create a new markdown note in your Obsidian vault with atomic, no-clobber writes. Optionally bind the write to a prior read to prevent overwriting concurrent changes.
Instructions
Create a new markdown note in the Obsidian vault. Requires write permission — a readwrite API key, or an OAuth token
carrying the readwrite scope.
See get_vault_guide for Obsidian syntax and any vault-specific conventions
(naming, folder placement, frontmatter, tags).
Refuses a path whose final component is a symlink, naming its target, so a write never lands on a note other than the one named; symlinked folders inside the vault work normally.
The note is published no-clobber: the content is staged out of sight and
linked into place in one kernel-atomic step, so an existing file at path
can never be replaced by this tool. A vault filesystem that cannot stage an
unnamed file refuses the write with an error naming
VAULT_ALLOW_NAMED_STAGING_FALLBACK rather than staging under a visible
name.
expected_hash — binding a write to the bytes you read. Optional; omit
it and nothing changes. Pass the content_hash a read returned, verbatim
and canonical (sha256:<64 lowercase hex>), and the call is refused with
nothing written if the file changed in between. It is always the whole
file's hash, never a hash of the text you received. Two windows, both
live: expected_hash covers your read → this call's read, the server's own
pre-publication compare covers this call's read → its publication, and a
match on the first does not exempt the second. Every refusal ends with one
machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with
the file's current hash, ready to resend), concurrent_write,
no_incumbent, malformed_precondition, precondition_unavailable,
precondition_required — and each states what resolves it.
Here there are no incumbent bytes to bind: a supplied hash is answered
no_incumbent before any filesystem work, nothing is created, and the
remedy is to call again without it. A malformed hash is still reported as
malformed first. Success reports the content_hash of the note this call
published.
Args:
path: Vault-relative path for the new note (e.g. "Cards/New Topic.md"). The .md extension is added if missing.
content: Full markdown content for the note, including any frontmatter.
expected_hash: Accepted and always refused as no_incumbent, so the
refusal is a normal result rather than a protocol error.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| expected_hash | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |