nvim-mcp 0.6.1

MCP server for AI-assisted control of Neovim via msgpack-RPC

nvim-mcp

An MCP server that gives AI agents first-class access to your running Neovim session. It connects through Neovim's native msgpack-RPC socket — no plugins required.

Works with Cursor, Claude Code, Codex, and any MCP-compatible client.

What agents can do

• See what you see — editor mode, working directory, open buffers, window layout, cursor context, folds, selections, marks, and diagnostics.
• Edit buffers in memory — find-and-replace or full rewrites with immediate feedback and full undo support. Nothing touches disk until you save.
• Run any Vim command — :w, :e, :vsplit, macros, or anything else you could type at the command line.
• Send keystrokes — navigate, enter insert mode, trigger mappings.
• Query LSP diagnostics — errors, warnings, and hints across one buffer or the whole session.
• Annotate code with highlights — colored extmarks to draw your attention to specific lines.

Anything you can do in Neovim, the agent can too. See the full tool reference for details.

Demos

Using nvim-mcp across two terminals

Using nvim-mcp with a terminal inside Neovim

Claude and Cursor collaborating in one Neovim instance

Using nvim-mcp in Cursor

Quick start

1. Install uv if you don't have it:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Register the MCP server with your client. Example for Cursor (.cursor/mcp.json):

   {
     "mcpServers": {
       "nvim-mcp": {
         "command": "uvx",
         "args": ["nvim-mcp"]
       }
     }
   }
   

   For Claude Code, Codex, Claude Desktop, and other clients, see the configuration guide.

3. Add agent rules so the agent knows when and how to use the tools:

   ./config/generate-configs.sh
   

   See the configuration guide for details.

4. Start Neovim — on most Linux systems it listens on a Unix socket automatically and is discovered by nvim-mcp. If auto-discovery doesn't work, see environment variables.

Verify it works

Open a file in Neovim and paste this into your AI agent:

For each step: explain what you're about to do, then do it, then tell me
what happened. Wait for me to say "next" before moving on.

1. What file am I in? Highlight the function my cursor is in.
2. Are there any diagnostics? Highlight any lines with errors or warnings.
3. Add a docstring above the function, then show me the diff.
4. Open a vertical split, write a short test for that function, and save both files.

Requirements

• Linux
• Python ≥ 3.10
• Neovim ≥ 0.11 (older versions work with --listen and NVIM_ADDRESS)

License

MIT — see LICENSE.