DOCSEARCHbyAlgolia
Submit Docs

Neovim MCP Server

repository·master·Indexed 43 days ago

https://github.com/bigcodegen/mcp-neovim-server

An MCP server (v0.5.5) that connects AI clients like Claude Desktop to a running Neovim instance via the Model Context Protocol. It provides 19 tools for complex text editing, navigation, and workflow management, including buffer and window manipulation, project-wide grep, macro recording, and code folding. It exposes resources like nvim://session and nvim://buffers to provide AI agents with real-time context of the editor state.

Tokens
3.7K
Snippets
7
Records
20
Agent score
51%

What's inside Neovim MCP Server

  1. Install the Neovim MCP Server

    master

    You can install the Neovim MCP Server using two methods:

    Option 1: DXT Package (Recommended)

    1. Download the latest .dxt file from the Releases page.
    2. Drag and drop the file into Claude Desktop.

    Option 2: Manual Installation

    Add the server configuration to your claude_desktop_config.json file using npx:

    {
  "mcpServers": {
    "MCP Neovim Server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-neovim-server"
      ],
      "env": {
        "ALLOW_SHELL_COMMANDS": "true",
        "NVIM_SOCKET_PATH": "/tmp/nvim"
      }
    }
  }
}
    {
  "mcpServers": {
    "MCP Neovim Server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-neovim-server"
      ],
      "env": {
        "ALLOW_SHELL_COMMANDS": "true",
        "NVIM_SOCKET_PATH": "/tmp/nvim"
      }
    }
  }
}

  2. Configure Neovim MCP Server environment variables

    master

    The server uses the following environment variables for configuration:

    • ALLOW_SHELL_COMMANDS: Set to 'true' to enable shell command execution (e.g., !ls). Defaults to false for security.
    • NVIM_SOCKET_PATH: The path to your Neovim socket. Defaults to '/tmp/nvim' if not specified.

  3. Troubleshoot Neovim MCP Server connections

    master

    The server uses specific error classes to help diagnose issues:

    • NeovimConnectionError: Occurs during socket connection failures.
    • NeovimCommandError: Occurs when a command execution fails.
    • NeovimValidationError: Occurs when input validation fails.

    Common Requirements:

    • Socket Connection: You must start Neovim with a socket exposed (e.g., nvim --listen /tmp/nvim). The server will not work with standard Vim without a socket.
    • Security: Shell command execution is disabled by default. If you need to run shell commands via vim_command, you must set the ALLOW_SHELL_COMMANDS environment variable to true.

  5. Use Neovim MCP Server tools for editing and navigation

    master

    The server provides 19 tools to allow an AI client to interact with a Neovim session.

    Core Editing and Navigation

    • vim_buffer: Get buffer contents with line numbers. Supports optional filename parameter.
    • vim_command: Send a command to VIM. Supports multiple commands with newlines. Shell commands are supported with ! prefix if ALLOW_SHELL_COMMANDS=true.
    • vim_edit: Edit lines using mode ("insert" | "replace" | "replaceAll") at a specific startLine.
    • vim_status: Get comprehensive status including cursor position, mode, filename, visual selection, window layout, marks, registers, and LSP info.
    • vim_window: Manipulate windows using commands like "split", "vsplit", "only", "close", or "wincmd h/j/k/l".
    • vim_visual: Create visual mode selections using startLine, startColumn, endLine, and endColumn.

    Buffer and File Management

    • vim_buffer_switch: Switch between buffers by identifier (string or number).
    • vim_buffer_save: Save current buffer or save to a specific filename.
    • vim_file_open: Open files into new buffers using filename.

    Search and Replace

    • vim_search: Search within current buffer with pattern, ignoreCase (boolean), and wholeWord (boolean).
    • vim_search_replace: Find and replace with pattern, replacement, global (boolean), ignoreCase (boolean), and confirm (boolean).
    • vim_grep: Project-wide search using vimgrep with pattern and optional filePattern.

    Advanced Workflow

    • vim_macro: Record, stop, or play macros using action ("record" | "stop" | "play"), register (a-z), and optional count.
    • vim_tab: Manage tabs with action ("new" | "close" | "next" | "prev" | "first" | "last" | "list").
    • vim_fold: Code folding with action ("create" | "open" | "close" | "toggle" | "openall" | "closeall" | "delete").
    • vim_jump: Navigate jump list with direction ("back" | "forward" | "list").

    System and State

    • vim_mark: Set named marks (a-z) at line and column.
    • vim_register: Set content of registers (a-z or ").
    • vim_health: Check Neovim connection health and socket status.

  6. Access Neovim session resources

    master

    The server exposes the following MCP resources:

    • nvim://session: Represents the current Neovim text editor session.
    • nvim://buffers: Provides a list of all open buffers in the current session, including metadata like modified status, syntax, and window IDs.

  7. Get Neovim status and environment information

    master

    Use getNeovimStatus() to retrieve a comprehensive snapshot of the current Neovim state. The returned NeovimStatus object includes:

    • cursorPosition: [line, col]
    • mode: Current mode (e.g., 'n', 'v', 'i')
    • visualSelection: The text currently selected in visual mode
    • fileName: Name of the current buffer
    • windowLayout: JSON string of the layout
    • marks: A map of set marks (a-z)
    • registers: A map of non-empty registers
    • cwd: Current working directory
    • lspInfo: Information about active LSP clients
    • pluginInfo: Detection of common plugins (LSP, Telescope, TreeSitter, etc.)
    • visualInfo: Details about active visual selections (start/end positions, mode type)

  8. Use Neovim MCP Tools for Editing and Buffer Management

    master

    The server provides a wide array of tools to manipulate Neovim buffers and files:

    • vim_buffer: Get buffer contents with line numbers. (Optional filename parameter).
    • vim_buffer_switch: Switch between buffers using a identifier (buffer number or filename/path).
    • vim_buffer_save: Save the current buffer or a specific filename.
    • vim_file_open: Open a file at a specific filename into a new buffer.
    • vim_edit: Edit buffer content. Requires startLine (1-indexed), mode (insert, replace, or replaceAll), and lines (the text content).
    • vim_visual: Create a visual mode selection using startLine, startColumn, endLine, and endColumn.
    • vim_mark: Set a named mark using mark (single lowercase letter [a-z]), line (1-indexed), and column (0-indexed).
    • vim_register: Store text in a register using register (lowercase letter [a-z] or " for unnamed) and content.

    Example: Editing a file

    {
  "name": "vim_edit",
  "arguments": {
    "startLine": 10,
    "mode": "insert",
    "lines": "Hello World"
  }
}

  9. Edit buffer lines and manage text

    master

    The editLines method allows for precise text manipulation within a buffer:

    • replace: Replaces lines starting at startLine with newText.
    • insert: Inserts newText at startLine without deleting existing lines.
    • replaceAll: Replaces the entire buffer content with newText.
    // Replace lines 5 through 10 with new content
await manager.editLines(5, 'replace', 'new line 1\nnew line 2');

// Replace the entire file content
await manager.editLines(1, 'replaceAll', 'entire file content');

  10. Use NeovimManager to interact with Neovim

    master

    The NeovimManager class is a singleton used to manage the connection and perform operations on a Neovim instance. It automatically handles connection via a socket path, which can be configured using the NVIM_SOCKET_PATH environment variable (defaults to /tmp/nvim).

    import { NeovimManager } from './path-to-neovim';

const manager = NeovimManager.getInstance();

// Example: Check if Neovim is healthy
const isHealthy = await manager.healthCheck();

// Example: Get current buffer contents
const contents = await manager.getBufferContents();

  11. Use Neovim MCP Tools for Macros and Folding

    master

    Advanced Neovim features:

    • vim_macro: Manage macros. action can be record, stop, or play. register is required for record and play. count is the number of times to play (default: 1).
    • vim_fold: Manage code folding. action can be create, open, close, toggle, openall, closeall, delete. startLine and endLine are required for create.

  12. Execute commands and search in Neovim

    master

    The NeovimManager provides several ways to execute commands and search text:

    • Send arbitrary commands: sendCommand(command: string) executes a Vim command. It handles leading colons and can execute shell commands if they start with ! and the ALLOW_SHELL_COMMANDS=true environment variable is set.
    • Search in buffer: searchInBuffer(pattern: string, options?: { ignoreCase?: boolean; wholeWord?: boolean }) performs a search and moves the cursor to the first match.
    • Search and replace: searchAndReplace(pattern: string, replacement: string, options?: { global?: boolean; ignoreCase?: boolean; confirm?: boolean }) performs a substitute command.
    • Grep in project: grepInProject(pattern: string, filePattern?: string) uses vimgrep to search for a pattern across files and returns a summary of the quickfix list.
    const manager = NeovimManager.getInstance();

// Execute a standard Vim command
await manager.sendCommand('wincmd l');

// Search for a pattern in the current buffer
await manager.searchInBuffer('function_name', { ignoreCase: true });

// Global search and replace
await manager.searchAndReplace('old_text', 'new_text', { global: true });

// Project-wide grep
const grepResults = await manager.grepInProject('TODO');