nvim

This MCP server exposes Neovim LSP-based symbol tools and general evaluation commands that let language models interact with Neovim's codebase. The symbol tools let you query and manipulate code structure at the symbol level, including getting an overview of top-level symbols, finding symbols by name, locating references, and performing edits such as replacing bodies or inserting content around symbols. General tools include the ability to execute Lua or Vimscript snippets inside Neovim, enabling dynamic behavior and on-the-fly experimentation within the editor context. To use the server in a client such as Claude Desktop or Goose, point the client at the MCP server instance (in this setup, the uv-based server named nvim-mcp) and ensure Neovim is running and accessible via the NVIM socket you configured. The server acts as an intermediary, translating LSP-aware operations and editor commands into actions that Neovim can perform, which is especially useful for AI-assisted refactoring, symbol renaming, and code exploration.

Prerequisites:

• Python 3.11+
• uv (the Python package manager for Neovim integration)
• Neovim 0.9+ with built-in LSP client

Install from source:

git clone https://github.com/brianhuster/nvim-mcp-server.git
cd nvim-mcp-server
uv sync

Configure Neovim to expose a socket and start the MCP when needed. To run the MCP server via uv, ensure Neovim is running and that the socket path is accessible to the MCP process, e.g.:

# Start Neovim with a listening socket (example)
nvim --listen /tmp/nvim.sock

Run the MCP server:

uv run nvim-mcp

Configure clients (Claude Desktop, Goose, etc.) to connect to the MCP server using the following example:

• Claude Desktop config:

{
  "mcpServers": {
    "nvim": {
      "command": "uv",
      "args": ["run", "nvim-mcp"],
      "env": {
        "NVIM": "/tmp/nvim.sock"
      }
    }
  }
}

• Goose example:

extensions:
  nvim-mcp:
    cmd: uv
    args: ["run", "nvim-mcp"]
    env:
      NVIM: "/tmp/nvim.sock"
    type: stdio

Notes:

• Ensure the NVIM environment variable points to the Neovim socket you started.
• The MCP server relies on Neovim’s LSP client; if Neovim stops or the socket is inaccessible, the MCP server will fail to communicate with the editor instance.
• You can customize the path to the Neovim plugin directory or runtimepath as needed for your setup.

Tips and common issues:

• If you see a failure to connect, verify that Neovim is running with --listen and that the NVIM socket matches exactly what the MCP server is configured to use.
• When performing symbol edits (replace/insert/rename), consider backing up the file before applying changes, as automated edits may impact surrounding code or formatting.
• For large projects, be mindful of symbol resolution depth in get_symbols_overview and related methods to keep responses performant.
• The server exposes Lua and Vimscript execution tools; use these to extend Neovim behavior during AI-driven workflows, but avoid executing untrusted code in production environments.
• If you need to run the MCP server in a containerized environment, ensure the container can access the host Neovim socket or expose a persistent socket path.