add_virtual_text
Overlay virtual text annotations on a Neovim buffer's lines. Choose position (eol, above, below) and color for visual-only feedback.
Instructions
Add a virtual text annotation to a Neovim buffer. Visual only — the buffer's actual content is unchanged and nothing is written to disk. Annotations stack; multiple calls accumulate.
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
line: 1-indexed anchor line. Out-of-range values are clamped.
text: list of strings, one per virtual line. Must be non-empty.
When position is "eol", exactly one item is allowed.
position: where the annotation appears relative to the anchor line.
One of "eol" (after end of line), "above" (between previous and
anchor lines), or "below" (between anchor and next lines).
Defaults to "eol".
color: a Neovim highlight group name (e.g. "Comment",
"DiagnosticError") or a hex color (e.g. "#7a9ad4"). Defaults to
"Comment", which adapts to the user's colorscheme. Unknown names
(including bare color literals like "Red") return an error.
Use this for a single annotation. Use add_virtual_texts for
multiple annotations in one call. Use clear_virtual_texts to
remove all MCP virtual text from a buffer.
Returns {added: 1} on success, or {error} with a message on failure.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| text | Yes | ||
| position | No | eol | |
| color | No | Comment |