Skip to main content
Glama

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.0

Any client that connects to that socket can drive the parent editor. nvim-mcp:

  1. reads NVIM (the default; this is set automatically inside a :terminal),

  2. connects to that socket over msgpack-RPC, and

  3. 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-mcp

From source:

git clone https://github.com/shooooooooo/nvim-mcp
cd nvim-mcp
npm install
npm run build

Use 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-mcp

Then start Claude Code from inside Neovim so it inherits $NVIM:

:terminal claude

That'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

nvim_info

Version, channel, cwd, current buffer/window, how the connection was resolved.

nvim_exec_lua

Run arbitrary Lua via nvim_exec_lua (the full power escape hatch).

nvim_command

Run an Ex command and capture its output.

nvim_eval

Evaluate a Vimscript expression.

nvim_list_buffers

List buffers (number, name, type, modified, line count).

nvim_read_buffer

Read lines from a buffer by number, path, or current.

nvim_write_buffer

Replace a line range in a buffer.

nvim_open_file

Open a file (optionally in a split or tab).

nvim_list_windows

List windows with buffer, size, cursor.

nvim_diagnostics

LSP/diagnostic entries for a buffer or all buffers.

nvim_run_in_terminal

Open a terminal, run one command, wait, return output + exit code.

nvim_open_terminal

Open a persistent terminal; returns its buffer/channel/job id.

nvim_terminal_send

Send input/keys to an open terminal.

nvim_terminal_read

Read a terminal's rendered contents.

nvim_list_terminals

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

nvim_lsp_clients

List the language servers attached to a buffer (and whether they've initialized).

nvim_lsp_hover

Hover docs (signatures, types) for the symbol at a position.

nvim_lsp_definition

Resolve definition location(s) of the symbol at a position.

nvim_lsp_references

Find all references to the symbol at a position.

nvim_lsp_document_symbols

List the symbols defined in a buffer (with kind and nesting depth).

nvim_lsp_rename

Rename a symbol project-wide; applies the edits (or previews with apply=false).

nvim_lsp_code_action

List code actions (quick fixes/refactors) at a position; apply one by index.

nvim_lsp_format

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:

  1. --socket <addr> / --address <addr> CLI flag

  2. NVIM_MCP_SOCKET

  3. NVIM (set automatically inside a Neovim :terminal)

  4. 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 test

What'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, run echo 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 with NVIM set, lists the tools, and calls nvim_run_in_terminal to run echo hello world end-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 test

Releasing

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-tags

The workflow typechecks, builds, and runs npm publish --provenance, so the published package always ships a fresh dist/.

License

MIT — see LICENSE.

Available Tools

23 tools
nvim_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

    A3.9/5.0

    Scored across 23 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that edits files through a real Neovim instance, giving agents access to LSP diagnostics, formatting, code actions, and plugin commands.
      10
      19 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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