Neovim MCP Server

A Model Context Protocol (MCP) server for Neovim that provides LSP-based symbol tools. This server enables AI language models to interact with Neovim's Language Server Protocol (LSP) for symbol-level code operations.

Features

Symbol Tools (LSP-based)

- get_symbols_overview(relative_path, depth) - Get overview of top-level symbols in a file. Use depth to include children (e.g., methods of a class).
- find_symbol(name_path_pattern, relative_path, depth) - Find symbols by name path pattern (e.g., "MyClass/my_method").
- find_referencing_symbols(name_path, relative_path) - Find all references to a symbol.
- replace_symbol_body(name_path, relative_path, body) - Replace the body of a symbol definition.
- insert_after_symbol(name_path, relative_path, body) - Insert content after a symbol's definition.
- insert_before_symbol(name_path, relative_path, body) - Insert content before a symbol's definition.
- rename_symbol(name_path, relative_path, new_name) - Rename a symbol throughout the codebase.
- restart_language_server() - Restart the LSP server (useful when LSP hangs).
- get_lsp_client_info() - Get information about active LSP clients.

General Tools

- execute_lua(code) - Execute Lua code in Neovim
- execute_vimscript(code) - Execute Vimscript code in Neovim

Installation

Prerequisites

- Python 3.11+
- uv package manager
- 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

Add to your Neovim configuration

Add the plugin directory to your Neovim runtime path:

-- In your init.lua or plugins.lua
vim.opt.runtimepath:append("/path/to/nvim-mcp-server/plugin")

Usage

Start Neovim with the MCP server

1. Start Neovim with a socket:

   nvim --listen /tmp/nvim.sock

   

2. Set the NVIM environment variable and run the MCP server:

   export NVIM=/tmp/nvim.sock

   uv run nvim-mcp

   

Configuration with Claude Desktop

Add this to your claude_desktop_config.json:

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

Use with Goose

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

Development

Commands

- uv run nvim-mcp - Start the MCP server
- uv run nvim-mcp --version - Show version
- uv run ruff check - Run linting
- uv run mypy - Run type checking