Replace in Note
vault_replace_in_noteFind and replace exact text in a markdown note body to fix typos, update values, rename terms, or delete a short line while leaving properties unchanged; enable all occurrences for bulk edits.
Instructions
Find and replace exact text in a markdown note's body. Properties are kept as written, and body line breaks are saved as LF. Edit properties via vault_update_properties or vault_write_note's properties parameter. A repeated call replaces old_text again if the note still holds it, including a copy inside the first call's new_text, so after a timeout or lost response, re-read the note before retrying.
Example: vault_replace_in_note({ path: "Projects/plan.md", old_text: "TODO: write summary", new_text: "Summary complete." }) Example: vault_replace_in_note({ path: "Projects/plan.md", old_text: "- [ ] draft outline\n", new_text: "" }) Example: vault_replace_in_note({ path: "Projects/plan.md", old_text: "Q3", new_text: "Q4", replace_all_occurrences: true })
When to use: Targeted text changes within a single location — fixing typos, updating values, renaming terms, or removing a short line (new_text=""). To delete a large multi-line block, prefer vault_delete_span (short anchors instead of full old_text). To replace a large block by anchors instead of reproducing the full old_text, use vault_replace_span. To relocate content between headings, use vault_patch_note to add at the target first, then remove from source (new_text="") — add-before-delete, so a failure duplicates the block instead of losing it.
Parameters:
old_text: include enough surrounding context to ensure uniqueness when the target text appears in multiple places.
replace_all_occurrences: set true for deliberate bulk renames or term replacements.
Behavior:
A non-empty new_text replaces the match exactly; new_text="" deletes it, and when text remains on the line, the line is written exactly as asked.
When new_text="" leaves the match's line empty, blank lines never double: the text above and below ends up separated by the wider of the two runs of empty lines that stood there, and by at least one.
At the note's end, where no text follows, the run of empty lines above is kept one line shorter ("A\n\nB\n" without "B" → "A\n").
To remove a table row or list item, include its line break in old_text, or the empty line left behind splits the table or list.
A line holding only spaces or tabs counts as text, not as an empty line.
Errors:
"note not found" — path does not exist; check vault_list_notes for valid paths
"path must end in …" — add the .md extension
"text not found" — old_text does not appear in the note body; verify exact text with vault_read_note
"absolute path blocked" / "path traversal blocked" / "hidden path blocked" — pass a vault-relative path with no dot-prefixed part
"concurrent write in progress" — a write to this note is in flight; re-read it and retry
"new_text contains a control character" — remove the character the message names
"ENAMETOOLONG: …" or another filesystem error — the message says what to do
"the note would open with a properties block …" — a note without properties would start with --- lines around text that can't be properties; the error says how to avoid it
Obsidian syntax: new_text is Obsidian Flavored Markdown (no escaping applied). Watch for: #word = tag, [[ = wikilink, %% = comment block in replacement text.
Returns: "Replaced occurrence(s) in ".
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>",
"old_text": "<old_text>",
"new_text": "<new_text>"
},
"name": "vault_replace_in_note"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note, including the ".md" extension (e.g. "Projects/plan.md"). Use the exact letter case. | |
| new_text | Yes | Replacement text; "" deletes the matched text. | |
| old_text | Yes | Exact text to find, no regex (case-sensitive). | |
| replace_all_occurrences | No | Replace all occurrences (default: false — replaces first occurrence only) |