neovim-use-mcp
This server lets an AI agent edit files through a real Neovim instance, giving access to LSP features, formatting, and plugins instead of plain text editing.
Open and read files as numbered Neovim buffers
Edit files with minimal diffs: replace line ranges, insert lines, or replace exact text
Save buffers without triggering format-on-save autocmds
Get LSP diagnostics, code actions, hover info, definitions, references, and symbol outlines
Rename symbols across the whole workspace via LSP
Format whole files or line ranges
Run arbitrary Neovim Ex commands or Lua code to drive plugins
List open buffers and search workspace symbols
Support multi-file workflows with staged saves
Choose a minimal (10 tools) or full (18 tools) tool set
Edits files through a real Neovim instance, providing LSP diagnostics, code actions, symbol renaming, references, hover, formatting, and access to Neovim commands and Lua scripting.
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., "@neovim-use-mcp Fix all TypeScript errors in src/utils.ts using LSP diagnostics and code actions"
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.
neovim-use-mcp
An MCP server that edits files through a real Neovim instance. Your agent gets your language servers, your formatters and your plugins, not a plain text writer.
Real LSP — diagnostics after every edit, rename, code actions, hover, references, document and workspace symbols.
Minimal diffs — edit tools save the buffer with
noautocmd writeby default, soBufWritePre(format-on-save) does not run. Only the edited lines change. Usenvim_formatto format explicitly.Plugin access —
nvim_commandandnvim_exec_luareach anything else.stdio transport — the server starts with the agent and stops with it. It also stops the Neovim child process.
Requirements
Item | Version | Note |
Node.js | 18 or later | The server runs on Node. |
Neovim | 0.10 or later | The server calls |
A Neovim config | optional | Without one, you get edits but no LSP. |
Check your Neovim first:
nvim --version
nvim --headless --embed # must start and stay quiet; press Ctrl-C to stopIf that command prints errors, a plugin breaks headless start. Use
--config-mode minimal until you fix the plugin.
Related MCP server: nvim-mcp
Install
From npm (recommended)
npm install -g neovim-use-mcpOr use npx without a global install:
npx neovim-use-mcpFrom source
git clone https://github.com/santanusinha/neovim-use-mcp.git
cd neovim-use-mcp
npm install
npm run buildThe build writes dist/index.js. That file is the server.
Connect an agent
Add the server to your MCP client config.
With npx (no install needed):
{
"mcpServers": {
"neovim": {
"command": "npx",
"args": ["neovim-use-mcp"],
"env": {
"NVIM_MCP_CWD": "/absolute/path/to/your/project"
}
}
}
}With a global install:
{
"mcpServers": {
"neovim": {
"command": "neovim-use-mcp",
"env": {
"NVIM_MCP_CWD": "/absolute/path/to/your/project"
}
}
}
}From a local build:
{
"mcpServers": {
"neovim": {
"command": "node",
"args": ["/absolute/path/to/neovim-use-mcp/dist/index.js"],
"env": {
"NVIM_MCP_CWD": "/absolute/path/to/your/project"
}
}
}
}NVIM_MCP_CWD sets the project root. The language server uses that root to
find tsconfig.json, go.mod, Cargo.toml and so on. If you leave it out,
the server uses the directory that the agent starts it in.
The server needs no start or stop command. The agent starts it over stdio and stops it on exit. The server then stops its Neovim child process.
First run
Ask your agent to open a file:
Open
src/util/format.tswith the Neovim tools.
A correct answer looks like this:
Opened src/util/format.ts (buffer 1, 59 lines, filetype typescript).
LSP clients: null-ls, quick_lint_js, ts_lsIf you see No LSP client attached, read
When no LSP attaches.
How an agent should work
The tools follow one simple order.
Open the file(s) with
nvim_open_file. Pass an array of paths to open several files at once. This starts the language server. Every LSP tool needs an open buffer.Read with
nvim_read_fileto get numbered lines.Edit with
nvim_edit_text,nvim_edit_linesornvim_insert_lines. Each edit saves the file and returns fresh diagnostics.Fix any new diagnostic with
nvim_code_actions.
Three rules make the results much better:
Use
nvim_rename_symbolfor a rename. Do not use a text replace. The LSP changes every file, and a text replace does not.Use
nvim_edit_textwhen you know the exact text. It fails if the text is not unique, which stops a wrong edit.Stage a multi-file change with
save: false, then callnvim_save_bufferonce per file.
Tools
The server loads one of two tiers. The --tools flag picks the tier.
minimal is the default and loads the 10 tools an agent runs all day.
full loads all 18 tools. No tool is deleted; the tier only decides what
loads into the agent's context.
Minimal tier (default, 10 tools)
Tool | Arguments | Purpose |
|
| Pre-warm files or tune the LSP wait. Other tools open files on demand |
|
| Read numbered lines |
|
| Replace a range, or insert before a line with |
|
| Format a file or a range |
|
| Rename across the workspace |
|
| Find a definition |
|
| Find every reference |
|
| Type and documentation |
|
| List or apply a quick fix |
|
| Run Lua inside Neovim |
Full tier adds (8 tools)
Tool | Arguments | Purpose |
|
| Replace exact text. Tolerates whitespace drift and preserves indentation |
|
| Insert text before a line. Prefer |
|
| Write a buffer (no format-on-save autocmds) |
|
| Errors and warnings for one file or all buffers |
| — | List open buffers |
|
| Outline a file |
|
| Search symbols in the project |
|
| Run an Ex command, for example a plugin command |
Lines and columns start at 1.
Edit tools save the buffer by default and return fresh diagnostics, both as
text and as a structured payload: { saved, line_count, errors, warnings, infos, diagnostics[] }.
nvim_exec_lua runs any code. Turn it off with --no-exec if the agent is
not trusted.
not trusted.
Recipes
Fix every error in a file
nvim_open_file path=src/app.ts
nvim_diagnostics path=src/app.ts severity=error
nvim_code_actions path=src/app.ts line=42 column=9 # list
nvim_code_actions path=src/app.ts line=42 column=9 apply_index=1Rename a symbol everywhere
nvim_open_file path=src/util/format.ts
nvim_document_symbols path=src/util/format.ts # find the line
nvim_rename_symbol path=src/util/format.ts line=28 column=17 new_name=renderIssuesThe tool returns the list of files that it changed and saved.
Change several places, then save once
nvim_edit_text path=src/a.ts old_text="foo(" new_text="bar(" save=false
nvim_edit_text path=src/a.ts old_text="= foo" new_text="= bar" save=false
nvim_save_buffer path=src/a.tsRun a plugin command
nvim_command command="Telescope find_files"
nvim_exec_lua code="return vim.fn.getcwd()"Options
Command line flags win over environment variables.
Flag | Environment | Default | Meaning |
|
|
|
|
|
| — | Socket for attach mode |
|
|
| Path to the nvim binary |
|
|
|
|
|
| exec on | Turn off |
|
|
|
|
|
| process cwd | Project root for the LSP |
|
|
| Default LSP wait |
|
|
| Diagnostics settle wait after an edit; floor 250 |
|
| off | Debug lines on stderr |
Watch the agent work
Attach mode shows you every edit in your own window, live.
Recipes
Fix every error in a file
nvim_read_file path=src/app.ts # implicit open
nvim_edit_lines path=src/app.ts start_line=42 end_line=42 text="..."
# feedback carries diagnostics
nvim_code_actions path=src/app.ts line=42 column=9 apply_index=1Rename a symbol everywhere
nvim_rename_symbol path=src/util/format.ts line=28 column=17 new_name=renderIssuesThe tool returns the list of files that it changed and saved.
Insert before a line
nvim_edit_lines path=src/app.ts start_line=5 end_line=4 text="import { join } from \"node:path\";"start_line = end_line + 1 means insert before start_line.
Stage several edits, then save once (full tier)
nvim_edit_lines path=src/a.ts start_line=10 end_line=10 text="..." save=false
nvim_edit_lines path=src/a.ts start_line=20 end_line=20 text="..." save=false
nvim_save_buffer path=src/a.tsRun a plugin command (full tier)
nvim_command command="Telescope find_files"
nvim_exec_lua code="return vim.fn.getcwd()"A tool is missing
The minimal tier loads 10 tools. Start the server with --tools full to load
all 18. Full-tier tool descriptions start with "Full-tier tool".
A language server does not attach
Check that the file type has a language server in your Neovim config.
Call
nvim_open_filewith a longerwait_ms, for example10000.Confirm the server starts in your own Neovim for the same file.
A stale swap file blocks or warns
The server never writes swap files and never stops on the E325 prompt. A
swap file that sits next to a target file is stale, or another editor owns
it. nvim_open_file still opens the file and prints a note:
Stale swap file ignored: /path/.file.txt.swp. Delete it to remove this note.Delete the .swp file to remove the note. The structured result carries
the path in stale_swap.
The server does not start
Run it by hand and read stderr:
NVIM_MCP_DEBUG=1 node dist/index.jsA healthy start prints:
[nvim-mcp] ready (mode=embedded, tools=minimal, exec=true, cwd=/your/project)A plugin breaks headless Neovim
Use --config-mode minimal. The server then runs nvim --clean. You keep the
edit tools, but you lose your plugins and your LSP setup.
Diagnostics look wrong or stale
A linter bridge, for example null-ls with eslint_d, reports an error when
the project has no lint config. Add the config, or make the null-ls source
conditional on a config file. This is an editor setup problem, not a server
problem.
A tool says the text is not unique
nvim_edit_text refuses an ambiguous match on purpose. Add more context lines
to old_text, or set replace_all: true if you truly want every match.
Development
npm run dev # tsc --watch
npm test # vitest, uses a real headless nvim
npm run typecheck # tsc --noEmit
npm run inspect # MCP Inspector UIDocker
A Dockerfile is included for isolated or CI usage. The image bundles Node and Neovim, but has no user Neovim config. Mount your config if you need LSP:
docker build -t neovim-use-mcp .
docker run --rm neovim-use-mcpReleasing
Releases publish to npm through GitHub Actions with OIDC trusted publishing. No npm token is stored.
Bump the version in
package.json.Tag and push:
git tag v0.x.0 && git push origin v0.x.0.Create a GitHub Release from the tag.
The
Publish to npmworkflow builds, tests, and publishes automatically.
Licence
MIT
This is completely vibe coded. I guarantee absolutely nothing!!
Available Tools
10 toolsnvim_code_actionsList or apply a code actionADestructive
List LSP code actions at a position. Pass apply_index to apply one and save the file. Use this to apply quick fixes for diagnostics.
Inputs: line (required), path (required), column (required), wait_ms, +1 more.
nvim_edit_linesReplace a line rangeADestructive
This is the default way to edit files. Use the provided line numbers to directly replace lines start_line..end_line (1-based, inclusive) with new text. To insert before a line, pass start_line = end_line + 1 (for example start 5, end 4 inserts before line 5). Saves the buffer by default without running format-on-save autocmds, so the diff is minimal. Returns fresh LSP diagnostics for the file. Use nvim_format to format after editing once editing and fixes on that are done.
Inputs: path (required), text (required), end_line (required), start_line (required), +1 more.
nvim_exec_luaRun Lua in NeovimADestructive
Run a Lua chunk inside Neovim and return its value. The chunk receives its arguments through ... and must use return to send a value back. Use this to reach plugins that have no dedicated tool.
Inputs: code (required), args.
nvim_formatFormat a fileAIdempotent
Format a whole file or a line range with the formatter Neovim is configured to use, then save it.
Inputs: path (required), wait_ms, end_line, start_line.
nvim_goto_definitionFind a definitionARead-onlyIdempotent
Find where the symbol at a position is defined, through the LSP.
Inputs: line (required), path (required), column (required), wait_ms.
nvim_hoverGet hover informationARead-onlyIdempotent
Get type and documentation information for the symbol at a position, the same text the editor shows on hover.
Inputs: line (required), path (required), column (required), wait_ms.
nvim_open_fileOpen files in NeovimAIdempotent
Open one or more files in Neovim buffers and start their LSP clients. Pass a single path or an array of paths. Returns the buffer id, filetype, line count and attached LSP clients for each file. Optional: use it to pre-warm files or tune wait_ms. Other tools open files on demand.
Inputs: path (required), wait_ms.
nvim_read_fileRead lines from a Neovim bufferARead-onlyIdempotent
Read a file through Neovim with line numbers. Opens the file if needed. Use start_line and end_line to read a slice of a large file.
Inputs: path (required), end_line, start_line.
nvim_referencesFind referencesARead-onlyIdempotent
Find every reference to the symbol at a position, through the LSP. Use this before a rename or a signature change.
Inputs: line (required), path (required), column (required), wait_ms.
nvim_rename_symbolRename a symbolADestructive
Rename a symbol across the whole workspace with the LSP, then save every changed file. Safer than a text search and replace.
Inputs: line (required), path (required), column (required), new_name (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct responsibility: LSP lookups (hover, definition, references), mutations (rename, edit, format, code actions), file I/O (read, open), and an escape hatch (exec lua). Even the similar-looking open vs read tools differ clearly in purpose: one returns buffer metadata, the other returns file content.
All tools share the consistent nvim_ prefix and most use a verb_noun pattern like nvim_read_file and nvim_rename_symbol. Minor deviations like nvim_references and nvim_code_actions being noun phrases, plus bare-verb tools like nvim_format and nvim_hover, keep this from being a perfect 5.
10 tools is a well-scoped set for a Neovim-powered editing and LSP server. Each tool covers a meaningful operation, and there is no obvious redundancy or bloat.
The core workflows are well covered: read, open, edit, format, rename, reference lookup, definition lookup, hover info, and code actions. Minor gaps exist around secondary LSP features like a dedicated diagnostics-only tool, document symbols, or explicit file create/delete operations, but agents can work around these.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server for agentverse documentation, generated by doc2mcp.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that enables AI agents to control Neovim instances running in tmux sessions.12MIT
- AlicenseAqualityDmaintenanceMake Neovim feel like Cursor. This MCP server gives an agent full control over the Neovim session it is running inside, including buffers, windows, diagnostics, LSP language intelligence, and terminals.23MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that exposes LSP-backed code navigation and editing tools to LLM agents using a single global config file to route file extensions to language servers.1MIT
- 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