neovim-mcp
Provides tools for code navigation in Neovim using LSP and Treesitter, allowing AI agents to get symbols, diagnostics, references, definitions, and manage the quickfix list.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@neovim-mcp find all references to the 'login' function and save to quickfix"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
open the project in Neovim
instruct the agent to e.g. find the flow of a feature in the codebase
the agent uses builtin bash tools (e.g.
grepandfind) as well as tools from this MCP to navigate the codethe 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: NeoVimMCP
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/nvimattach 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 build3. 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.jsfor 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.jsother 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 |
| File outline via LSP (with optional name filter) |
| Treesitter Abstract syntaxt tree at a cursor position |
| Workspace-wide symbol search via LSP |
| LSP errors/warnings for a file or workspace |
| Find all usages of a symbol |
| Jump to where a symbol is defined |
| Find implementations of an interface/abstract method |
| Type signature and docs at a position for a symbol |
| Read/write the Neovim quickfix list |
| Restart LSP clients (useful after external file changes) |
| get active LSP clients |
| Check connection with the Neovim instance |
Compared to other projects
Project | Diffs |
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.
Available Tools
14 toolsget_ast_contextA
Get the treesitter scope chain at a position (shows enclosing functions, classes, blocks)
Inputs: file (required), line (required).
get_diagnosticsB
Get LSP diagnostics (errors, warnings) for a file or the entire workspace
Inputs: file, severity.
get_document_symbolsA
Get LSP document symbols for a file (functions, classes, types with line numbers and nesting). Optionally filter by name.
Inputs: file (required), query.
get_lspB
get all running LSP clients and all available ones
Inputs: no named parameters.
get_quickfixA
Get the current Neovim quickfix list contents
Inputs: no named parameters.
get_referencesB
Find all references to a symbol at a given position via LSP
Inputs: col (required), file (required), line (required).
goto_definitionB
Go to definition of a symbol at a given position via LSP
Inputs: col (required), file (required), line (required).
goto_implementationA
Find implementations of an interface or abstract method via LSP
Inputs: col (required), file (required), line (required).
hoverA
Get LSP hover information (type signature, documentation) for a symbol at a position
Inputs: col (required), file (required), line (required).
restart_lspA
Restart all running LSP clients. Use after making changes to files outside Neovim to refresh diagnostics and symbol data.
Inputs: no named parameters.
set_quickfixC
Set the Neovim quickfix list with a list of locations (e.g. feature touchpoints, search results, related code sites)
Inputs: items (required), title.
start_lspC
start a specific LSP server
Inputs: name (required).
vim_healthA
Check Neovim connection health
Inputs: no named parameters.
workspace_symbolsB
Search workspace symbols via LSP (functions, classes, types across the project)
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct action: LSP diagnostics, symbols, references, definitions, implementations, hover info, and workspace symbols are all clearly separate. AST context, quickfix management, LSP client control, and health check are also unique, so no overlap.
Most tools follow a verb_noun pattern in snake_case (e.g., get_diagnostics, goto_definition). However, 'workspace_symbols' lacks a verb prefix unlike its counterpart 'get_document_symbols', and 'vim_health' could be more descriptive. Overall, the naming is mostly consistent.
14 tools is well-scoped for a Neovim MCP server covering LSP interactions, AST queries, quickfix operations, and server health. Each tool serves a clear purpose without unnecessary bloat or deficiency.
The toolset thoroughly covers code navigation and LSP features (symbols, references, definitions, diagnostics, hover). Missing features like code actions or formatting, but these are likely out of scope for a read-only assistant. Minor gap: no way to get buffer content or edit files.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes type-aware code navigation and fast file search to AI agents via language servers, enabling definitions, references, symbols, and file lookup without reading entire codebases.2,580 npmMIT
- AlicenseAqualityBmaintenanceEnables AI clients to interact with Neovim buffers via MCP tools, providing buffer and cursor context.66 npmISC
- AlicenseAqualityBmaintenanceEnables LLM agents to navigate source code structurally via tree-sitter over MCP, offering outline-based reading, AST pattern search, workspace-scale symbol indexing, call graph analysis, and built-in security audit queries.15MIT
- AlicenseCqualityCmaintenanceEnables coding agents to navigate large codebases through a tree-sitter symbol graph, retrieve compact path:line-annotated context, and run a SNIPE fix loop with live dashboard updates on every save.38MIT