neovim-mcp

Make your AI agent leverage Neovim for code navigation.

This MCP server allows you to access your Neovim instance so that your AI agent can:

• use LSP functionalities: go to definition, find references, find symbols etc.

• use Treesitter to inspect the AST (abstract syntaxt tree)

• read and write to your quickfix list

How I use it

This is my typical workflow:

1. open the project in Neovim

2. instruct the agent to e.g. find the flow of a feature in the codebase

3. the agent uses builtin bash tools (e.g. grep and find) as well as tools from this MCP to navigate the code

4. the agent returns a summary of the feature and saves the result locations to the Neovim quickfix list, with details for each location

Requirements

• a Neovim installation with LSP servers and treesitter

• tested with Neovim 0.11. Older versions might work but they it's not guaranteed.

• Node.js to run the MCP server

Related MCP server: AiDD MCP Server

Setup

1. Start Neovim on the reserved socket

The MCP server talks to Neovim over a unix socket at /tmp/nvim. You must use the --listen option when starting Neovim. You have a couple of options:

• directly from the terminal when invoking the program: nvim --listen /tmp/nvim

• attach the instance to the socket at startup from your Neovim config:

  -- init.lua
  vim.fn.serverstart("/tmp/nvim")

• If you run multiple Neovim instances, add a toggle keymap — it lets you change which instance the MCP server talks to:

  -- keymaps.lua
  vim.keymap.set("n", "<leader>ts", function()
    if vim.tbl_contains(vim.fn.serverlist(), "/tmp/nvim") then
      vim.fn.serverstop("/tmp/nvim")
      vim.notify("MCP server released")
    else
      os.remove("/tmp/nvim")
      vim.fn.serverstart("/tmp/nvim")
      vim.notify("MCP server assigned to this instance")
    end
  end, { desc = "[T]oggle MCP [S]erver to this instance" })

2. Build the server

This server is so simple that downloading a release is not worth it. You can just clone this repo and build the JS files with the following:

npm install && npm run build

3. Register the server with your MCP client

Depending on your agent harness of choice this step might look different:

• for Claude Code:

  claude mcp add --transport stdio --scope user neovim-nav -- node /path/to/neovim-mcp/build/index.js

• for other clients (Cursor, etc.): add this to your MCP config file

  {
    "neovim-nav": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/neovim-mcp/build/index.js"]
    }
  }

3.1. Custom socket

The server connects to /tmp/nvim by default. To use a different socket path specify the env variable NVIM_SOCKET_PATH:

• Claude code:

  claude mcp add --transport stdio --scope user neovim-nav -e NVIM_SOCKET_PATH=/tmp/my-nvim -- node /path/to/neovim-mcp/build/index.js

• other clients:

  {
    "neovim-nav": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/neovim-mcp/build/index.js"],
      "env": { "NVIM_SOCKET_PATH": "/tmp/custom-nvim-socket" }
    }
  }

Remember to connect both your server and Neovim instance to the same socket: nvim --listen /tmp/custom-nvim-socket

Tools

Compared to other projects

Contributing

See src/README.md for project structure and how to add new tools.