nvim-mcp
Provides tools to control Neovim buffers, windows, diagnostics, LSP language intelligence, and terminals, enabling an AI agent to drive the editor session as if it were a user.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nvim-mcp open a terminal, run tests, fix failures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nvim-mcp
Make Neovim feel like Cursor. nvim-mcp is a Model Context Protocol
server that gives an agent — such as Claude Code —
full control over the Neovim session it is running inside: buffers, windows,
diagnostics, LSP language intelligence (definition, references, hover,
rename, code actions), and, crucially, terminals.
When you launch an agent from inside a Neovim :terminal, the agent isn't just
editing files in a vacuum — it's living inside your editor. nvim-mcp lets it
act like it: open a split, read a buffer, check LSP diagnostics, spin up a
terminal, run a command, and read the output back — the same things you'd do by
hand.
Why not just claudecode.nvim?
Plugins like claudecode.nvim expose the file being edited to the agent. That
is useful, but the agent still can't see or drive the rest of the editor — most
notably it cannot open a terminal inside Neovim, run something, and read the
result. nvim-mcp connects to Neovim's own RPC channel, so the agent gets the
whole editor, terminals included.
Related MCP server: @aetherall/mcp-nvim-tmux
How it works
Neovim is a first-class RPC server. Whenever Neovim spawns a child process — a
:terminal, jobstart(), system() — it exports the address of its own
msgpack-RPC socket in the NVIM environment variable:
$ nvim # inside Neovim, open a terminal with :terminal
$ echo $NVIM
/run/user/1000/nvim.1234.0Any client that connects to that socket can drive the parent editor. nvim-mcp:
reads
NVIM(the default; this is set automatically inside a:terminal),connects to that socket over msgpack-RPC, and
exposes a focused set of MCP tools that the agent can call.
┌──────────────────────────── Neovim ────────────────────────────┐
│ your code buffers, windows, LSP diagnostics │
│ │
│ ┌─ :terminal ──────────────────────────────────────────────┐ │
│ │ $ claude ($NVIM is set in here) │ │
│ │ └── nvim-mcp ──msgpack-RPC──┐ │ │
│ └─────────────────────────────────┼────────────────────────┘ │
│ controls buffers/terminals │ │
│ ◄─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Install
npm install -g nvim-mcp # or run on demand with: npx -y nvim-mcpFrom source:
git clone https://github.com/shooooooooo/nvim-mcp
cd nvim-mcp
npm install
npm run buildUse with Claude Code
Register the server so Claude Code can launch it. The simplest way is a
project-level .mcp.json (see examples/mcp.json):
{
"mcpServers": {
"nvim": { "command": "npx", "args": ["-y", "nvim-mcp"] }
}
}or globally:
claude mcp add nvim -- npx -y nvim-mcpThen start Claude Code from inside Neovim so it inherits $NVIM:
:terminal claudeThat's it — the agent can now call the nvim_* tools and they act on the editor
it's running inside. Ask it things like "open a terminal and run the tests, then
fix whatever fails."
Tools
Tool | What it does |
| Version, channel, cwd, current buffer/window, how the connection was resolved. |
| Run arbitrary Lua via |
| Run an Ex command and capture its output. |
| Evaluate a Vimscript expression. |
| List buffers (number, name, type, modified, line count). |
| Read lines from a buffer by number, path, or current. |
| Replace a line range in a buffer. |
| Open a file (optionally in a split or tab). |
| List windows with buffer, size, cursor. |
| LSP/diagnostic entries for a buffer or all buffers. |
| Open a terminal, run one command, wait, return output + exit code. |
| Open a persistent terminal; returns its buffer/channel/job id. |
| Send input/keys to an open terminal. |
| Read a terminal's rendered contents. |
| List open terminal buffers and whether they're still running. |
LSP tools — the editor's language intelligence
These let the agent use the language servers Neovim already has running, instead of re-deriving semantics from raw text. Positions are 1-based line and 1-based column.
Tool | What it does |
| List the language servers attached to a buffer (and whether they've initialized). |
| Hover docs (signatures, types) for the symbol at a position. |
| Resolve definition location(s) of the symbol at a position. |
| Find all references to the symbol at a position. |
| List the symbols defined in a buffer (with kind and nesting depth). |
| Rename a symbol project-wide; applies the edits (or previews with |
| List code actions (quick fixes/refactors) at a position; apply one by index. |
| Format a buffer via its language server and apply the changes. |
Targeting a specific Neovim
By default the target is discovered from the environment, highest priority first:
--socket <addr>/--address <addr>CLI flagNVIM_MCP_SOCKETNVIM(set automatically inside a Neovim:terminal)NVIM_LISTEN_ADDRESS(legacy)
<addr> may be a unix-socket path / named pipe, or a host:port TCP address
(start Neovim with nvim --listen 127.0.0.1:6789 for the latter).
Testing
The test suite is real, not mocked: every integration test spins up an actual
headless Neovim, points NVIM at it, and drives it exactly as the agent would.
npm testWhat's covered:
test/nvim.test.ts— the controller against a live Neovim: address resolution, session info, Lua/eval/Ex commands, buffer read/write, windows, diagnostics.test/terminal.test.ts— the headline scenario: open a terminal, runecho hello world, read it back; plus non-zero exit codes and interactive send/read.test/lsp.test.ts— the LSP tools driven against a deterministic fake language server (test/helpers/fake-lsp.mjs), covering hover, definition, references, document symbols, rename (apply + preview), code actions, and formatting — all offline, no real language server or network required.test/mcp.test.ts— the full MCP stack: an MCP client launches the server as a subprocess withNVIMset, lists the tools, and callsnvim_run_in_terminalto runecho hello worldend-to-end over JSON-RPC.
The reusable harness in test/helpers/nvim.ts starts a
pristine headless Neovim (-u NONE -i NONE -n) on a fresh socket and tears it
down cleanly, so you can build more scenarios on top of it. CI
(.github/workflows/ci.yml) runs the whole thing
against multiple Node and Neovim versions.
Real end-to-end with the live agent
npm test deliberately avoids needing an API key — it drives the MCP server
directly, which is the exact code path the agent uses. To verify the literal
"Claude Code inside Neovim" loop with the real LLM, see
scripts/e2e-claude-code.sh: it starts Neovim,
launches Claude Code in an in-editor terminal, and asks it to run
echo hello world in a Neovim terminal and read it back. That script needs the
claude CLI authenticated and is kept out of the automated suite for that
reason.
Development
npm install
npm run dev # run the server from TypeScript (tsx)
npm run typecheck
npm run build
npm testReleasing
Publishing to npm is automated by
.github/workflows/release.yml, which runs on
any pushed v* tag (or manually from the Actions tab). One-time setup: add an
NPM_TOKEN repository secret (an npm automation token with publish rights).
Then cut a release:
npm version patch # or minor / major — bumps package.json and tags it
git push --follow-tagsThe workflow typechecks, builds, and runs npm publish --provenance, so the
published package always ships a fresh dist/.
License
MIT — see LICENSE.
Available Tools
23 toolsnvim_commandRun Ex commandA
Execute an Ex command (e.g. :write, :bnext, :vsplit foo.txt) and return its captured output.
Inputs: command (required).
nvim_diagnosticsGet diagnosticsA
Return LSP/diagnostic entries (errors, warnings, etc.) for a buffer, or for all buffers if none is given. Great for letting the agent see and fix problems the way Cursor does.
Inputs: bufnr.
nvim_evalEvaluate VimL expressionA
Evaluate a Vimscript expression (e.g. expand('%:p')) and return the result.
Inputs: expr (required).
nvim_exec_luaExecute LuaA
Run Lua in Neovim via nvim_exec_lua and return the result as JSON. The code is a function body, so use return to produce a value and reference call arguments via .... This is the most powerful tool: anything the Neovim Lua API can do is reachable here.
Inputs: code (required), args.
nvim_infoNeovim session infoA
Report the connected Neovim instance: version, channel, working directory, current buffer/window and how the connection was resolved. Use this first to confirm the agent is wired to a live Neovim.
Inputs: no named parameters.
nvim_list_buffersList buffersA
List all buffers with their number, name, type, modified state and line count. Terminal buffers report buftype 'terminal'.
Inputs: no named parameters.
nvim_list_terminalsList terminalsA
List terminal buffers currently open in Neovim, with their job/channel and running state.
Inputs: no named parameters.
nvim_list_windowsList windowsA
List open windows with their buffer, size and cursor position.
Inputs: no named parameters.
nvim_lsp_clientsList LSP clientsA
List the language servers attached to a buffer (or the current buffer), with their id, name, root directory and whether they have finished initializing. Use this to check language intelligence is available before calling the other nvim_lsp_* tools.
Inputs: bufnr.
nvim_lsp_code_actionLSP code actionsA
List the code actions (quick fixes, refactors) the language server offers at a position, including any diagnostics there. Pass applyIndex (1-based, from a previous listing) to apply one of them.
Inputs: col, line, path, bufnr, +1 more.
nvim_lsp_definitionLSP go to definitionA
Resolve the definition location(s) of the symbol at a position. Returns file, line and column (1-based) for each location.
Inputs: col, line, path, bufnr.
nvim_lsp_document_symbolsLSP document symbolsA
List the symbols (functions, classes, variables, …) defined in a buffer, with their kind and line. Nesting is reported via depth.
Inputs: bufnr.
nvim_lsp_formatLSP format bufferA
Format a buffer using its language server and apply the changes in place.
Inputs: bufnr.
nvim_lsp_hoverLSP hoverA
Get hover documentation (signatures, types, docs) for the symbol at a position, as the editor's language server would show it.
Inputs: col, line, path, bufnr.
nvim_lsp_referencesLSP find referencesB
Find all references to the symbol at a position across the project.
Inputs: col, line, path, bufnr, +1 more.
nvim_lsp_renameLSP rename symbolA
Rename the symbol at a position project-wide via the language server and apply the resulting edits (set apply=false to preview which files would change without modifying anything).
Inputs: newName (required), col, line, path, +2 more.
nvim_open_fileOpen fileB
Open a file in Neovim, optionally in a split or new tab, and return its buffer info.
Inputs: path (required), split.
nvim_open_terminalOpen a terminalA
Open a persistent terminal inside Neovim and return its buffer number, channel and job id. Use nvim_terminal_send to type into it and nvim_terminal_read to read its screen. Use this for interactive or long-running sessions; for one-shot commands prefer nvim_run_in_terminal.
Inputs: cmd, cwd, name, focus, +1 more.
nvim_read_bufferRead bufferA
Read lines from a buffer (by number, path, or the current buffer). Line range is 0-based and end-exclusive; end = -1 reads to the end.
Inputs: end, path, bufnr, start.
nvim_run_in_terminalRun command in a terminalA
Open a terminal inside Neovim, run a single shell command, wait for it to finish, and return its output and exit code. This is the one-shot building block: e.g. run echo hello world and read it back. The terminal runs inside the user's editor, so the command shares the editor's environment and working directory.
Inputs: cmd (required), cwd, shell, split, +2 more.
nvim_terminal_readRead terminalA
Read the rendered contents (scrollback + current screen) of a terminal buffer. Trailing blank lines are trimmed by default.
Inputs: bufnr (required), stripTrailingBlank.
nvim_terminal_sendSend to terminalA
Send input to an open terminal buffer. By default a carriage return is appended so the line is submitted; set enter=false to send raw keys (e.g. control characters).
Inputs: data (required), bufnr (required), enter.
nvim_write_bufferWrite buffer linesA
Replace a line range in a buffer with new lines. Line range is 0-based and end-exclusive; use start = 0, end = -1 to replace the whole buffer.
Inputs: lines (required), end, path, bufnr, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool targets a distinct area: LSP operations, buffer manipulation, terminal control, and general commands. Even overlapping tools like nvim_command and nvim_exec_lua are clearly differentiated by their descriptions (Ex commands vs. Lua expressions). No two tools appear to do the same thing.
All tools share the nvim_ prefix and use lowercase with underscores, making them predictable. However, there is a mix of verb-first (nvim_read_buffer, nvim_open_file) and noun-first (nvim_terminal_send, nvim_lsp_clients) patterns, which is slightly inconsistent but still readable.
At 23 tools, this is on the heavier side but appropriate for the broad scope of controlling a Neovim instance. The tools are not redundant; each covers a distinct capability. The count feels reasonable for the complexity of the domain, though it borders on being overwhelming.
The surface is quite comprehensive: LSP operations, buffer I/O, terminal management, and general command execution are all covered. Minor gaps exist, such as lack of buffer deletion or window creation tools, but the included nvim_exec_lua tool can fill these gaps, and the core workflows are well covered.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server wrapping the Cursor CLI agent, enabling Claude Code and other MCP clients to delegate tasks to Cursor's AI agent for file writing, bash commands, and codebase queries.-
- AlicenseBqualityDmaintenanceAn MCP server that enables AI agents to control Neovim instances running in tmux sessions.12MIT
- AlicenseAqualityBmaintenanceAn MCP server that edits files through a real Neovim instance, giving agents access to LSP diagnostics, formatting, code actions, and plugin commands.1019 npmMIT
- AlicenseNot gradedqualityCmaintenanceMCP server bridging tool calls to Neovim editor actions via RPC. Enables AI agents to open files, run Lua, manage quickfix lists, fetch diagnostics, and send notifications.GPL 2.0