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

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

Multiple Neovim instances

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.

   uv

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

   Nix

   Install Nix — flakes must be enabled.

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

   With uv

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

   With Nix

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

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

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

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