Skip to main content
Glama
neovim-mcp
by Simonoob

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: 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/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.

Available Tools

14 tools
get_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

    A3.6/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes 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 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      15
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      38
      MIT