nvim-mcp

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, OpenCode, and any MCP-compatible client.

_Before you connect an agent to Neovim, please read Working safely._

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 and virtual text — colored line highlights and inline/above/below text notes that never touch the buffer's real content.
• Work with multiple instances — auto-discovers running sessions and connects to the right one. See multiple instances.

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

Demos

<details open> <summary>Using nvim-mcp across two terminals</summary>

<video src="https://github.com/user-attachments/assets/6de3f7a4-9c12-4a2f-96d9-d02d21935d37"></video>

</details>

<details> <summary>Using nvim-mcp with a terminal inside Neovim</summary>

<video src="https://github.com/user-attachments/assets/93fd17a6-0f93-48db-8428-d1cba51e29f2"></video>

</details>

<details> <summary>Claude and Cursor collaborating in one Neovim instance</summary>

<video src="https://github.com/user-attachments/assets/d92915ec-2108-4166-9911-4d09a5025865"></video>

</details>

<details> <summary>Using nvim-mcp in Cursor</summary>

<video src="https://github.com/user-attachments/assets/388f5f39-ab4d-4747-9eca-e09c666439ee"></video>

</details>

<details> <summary>Multiple Neovim instances</summary>

<video src="https://github.com/user-attachments/assets/15fa449e-0296-4815-8bfc-b9c33b5075bb"></video>

</details>

Quick start

nvim-mcp runs via uv (recommended) or Nix.

Cursor users: A Marketplace plugin is pending review — once available, it installs the MCP server and agent rule together (you can skip to step 4). To activate the rule, start chats with something like _"Connect to my Neovim instance"_ — or set the rule to "Always" in Settings → Rules to apply it on every turn.

1. Install a launcher.

<details open> <summary><strong>uv</strong></summary>

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

</details>

<details> <summary><strong>Nix</strong></summary>

Install Nix — flakes must be enabled.

</details>

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

<details open> <summary><strong>With uv</strong></summary>

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

</details>

<details> <summary><strong>With Nix</strong></summary>

   {
     "mcpServers": {
       "nvim-mcp": {
         "command": "nix",
         "args": ["run", "github:paulburgess1357/nvim-mcp"]
       }
     }
   }

</details>

<br>

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

1. Add agent rules — do not skip this. Without rules, the agent has the tools but doesn't know when or how to use them, and behavior will be unreliable. See the configuration guide for setup.

1. 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. Running multiple instances? See multiple instances.

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.

Working safely

The tools and agent rules are designed to use non-destructive operations — edits happen in memory, undo history is preserved, and the agent is steered toward buffer operations. But LLMs are non-deterministic, have full access to Neovim's API, and you should assume they will make mistakes. Work in a version-controlled directory.

Requirements

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

License

MIT — see LICENSE.