Nvim MCP

Connect to a running Neovim instance over its Unix socket or TCP address. Call this before any other tool if the agent is not yet connected. Connection is persistent for the session; you only need to call it once unless you want to switch instances. Called with no arguments: auto-connects when exactly one instance is running; returns a list of instances when multiple are found. Optional selection (provide at most one): - index: pick from the listed instances (1-based). - socket_path: connect directly to a known Unix socket or host:port. - terminal_pid: find the Neovim instance whose process tree contains this PID (useful when Neovim runs inside a specific terminal). Returns {connected, cwd, file} on success, or {error} with details on failure (e.g. no instances found, connection timeout, bad index).

Run one or more Vim ex commands in Neovim. This is a mutation tool — commands can modify buffers, files on disk, windows, and editor state. command: a single command string or a list of strings, without the leading ':'. E.g. "w", "e src/main.py", "42", "wincmd v", "lua vim.print(...)", or ["wincmd p", "e file.py", "wincmd p"]. Use this for editor operations that don't have a dedicated tool (e.g. saving, opening files, splitting windows, setting options). Use `send_keys` instead when you need normal-mode motions or operator sequences. Use `find_and_replace_buf` or `write_full_buf` for buffer text edits — they are safer and provide undo. Returns {output} with the command's captured output, or {error} if the command failed. When given a list, returns a list of results in the same order; execution stops on the first error.

Send raw keystrokes to Neovim as if typed by the user. This is a mutation tool — keystrokes can modify buffers, change mode, and trigger editor actions. keys: a string of Vim keystrokes. Esc is prepended automatically, so input always begins in normal mode. Multi-mode sequences must be sent in a single call (e.g. "17GVG", not "17GV" then "G"). Use Vim notation for special keys (e.g. "<CR>", "<C-w>v", "<Tab>"). Use this for normal-mode motions, visual selections, or operator sequences. Use `send_command` for ex commands, and `find_and_replace_buf` or `write_full_buf` for text edits — they are safer and provide structured results. Returns {sent} confirming the keys that were dispatched. Keystrokes are fire-and-forget; errors from the resulting Vim actions are not captured in the return value.

Type text into a terminal buffer's running program (usually a shell) by writing to its job channel. This is a mutation tool — the text reaches the program's stdin as if typed, but is not executed unless submit is true. text: the text to send, raw. In most shells an embedded newline acts like pressing Enter, so multi-line text may execute line by line. When submit is false, trailing newlines are stripped so nothing runs by accident. terminal: which terminal to target — a buffer number or buffer name, as listed under `terminals` in `get_state` / `get_state_brief`. Names match exactly first, then by unique substring. Omit it when exactly one terminal exists; with several open, omitting it returns an error listing them. submit: false (default) leaves the text at the prompt for the user to review and press Enter. true appends a carriage return so the program executes it immediately. NEVER pass submit=true unless the user has explicitly asked for the command to be run — "put", "paste", "type", or "prepare" a command always means submit=false. Suggesting a command yourself is not permission to run it. When in doubt, use submit=false and let the user press Enter. Use this whenever text needs to go into a terminal. It works regardless of focus, mode, or visibility and never moves the user's cursor — unlike `send_keys`, which requires focusing the terminal and juggling modes. Terminal buffers cannot be edited with the buffer tools. Returns {sent, terminal, buf, submitted} on success — sent is the byte count actually written. On failure returns {error}, including a `terminals` list when the target was missing or ambiguous.

Get LSP diagnostics from all open buffers in Neovim. Read-only. Use this for a project-wide overview of errors and warnings. Use `get_buf_diagnostics` instead when you only need diagnostics for a specific file — it is more focused and returns less data. Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when there are no diagnostics. Results depend on which LSP servers are attached and which buffers are loaded in Neovim.

Get LSP diagnostics for a single Neovim buffer. Read-only. 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. Use this when you need diagnostics for one specific file. Use `get_all_diagnostics` instead for a project-wide overview. Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when the buffer has no diagnostics.