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

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

Tool	Description
get_document_symbols	File outline via LSP (with optional name filter)
get_ast_context	Treesitter Abstract syntaxt tree at a cursor position
search_symbols	Workspace-wide symbol search via LSP
get_diagnostics	LSP errors/warnings for a file or workspace
get_references	Find all usages of a symbol
goto_definition	Jump to where a symbol is defined
goto_implementation	Find implementations of an interface/abstract method
hover	Type signature and docs at a position for a symbol
get_quickfix / set_quickfix	Read/write the Neovim quickfix list
restart_lsp	Restart LSP clients (useful after external file changes)
get_lsp	get active LSP clients
vim_health	Check connection with the Neovim instance

Compared to other projects

Project	Diffs
mcp-neovim-server	mcp-neovim-server is about overall control of your Neovim instance, with focus on text editing. This project focuses only on code navigation instead.

Contributing

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