mcp-neovim-server

Translates Model Context Protocol requests into Neovim RPC calls via Unix socket communication managed by a NeovimManager singleton. The server implements a three-layer architecture (MCP interface, application logic, socket integration) that maintains a persistent connection to running Neovim instances and serializes/deserializes RPC payloads, enabling AI clients to control Neovim as a remote process without direct binary dependencies.

Exposes the nvim://buffers resource that lists all open buffers with metadata (filename, line count, modification status) and implements vim_buffer tool to read full buffer content or specific line ranges. The system maintains awareness of which buffers are currently loaded in the editor session, enabling AI clients to query editor state and extract code context without requiring file system access.

Implements vim_visual_select tool that creates visual selections (character, line, or block mode) on specified line ranges, and vim_get_selection that retrieves currently selected text. The tools use Neovim's cursor positioning and mode-setting RPC calls to establish selections, then enable subsequent operations (delete, copy, format) on the selected range. Selections are mode-aware (visual, visual-line, visual-block).

Implements vim_set_mark and vim_goto_mark tools for creating and navigating to named marks, and vim_get_register/vim_set_register for accessing Vim's register storage. Marks are stored in Neovim's mark table (nvim_buf_set_mark, nvim_buf_get_mark) and registers are accessed via the register API. This enables AI clients to bookmark positions and store text snippets for later retrieval without external state management.

Implements vim_create_tab, vim_close_tab, and vim_switch_tab tools for managing Neovim's tab interface, and vim_split_window/vim_close_window for window management. The tools use Neovim's tab and window RPC API (nvim_command for :tabnew, :split, etc.) to manipulate the editor layout. Tab and window state is queryable through the session resource.

Implements vim_fold and vim_unfold tools that manage code folding using Neovim's folding API. The tools use Neovim's fold commands (:fold, :unfold) to collapse/expand code regions based on syntax or manual folds. vim_get_folds retrieves fold structure for the current buffer, enabling AI clients to understand code organization and navigate at the structural level rather than line-by-line.

Exposes neovim_workflow prompt that provides contextual guidance for using the Neovim MCP server effectively. The prompt includes best practices, common patterns, and workflow recommendations tailored to the user's current editor state. Prompts are static templates that MCP clients can include in their system prompts to guide AI behavior when interacting with Neovim.

Implements robust error handling throughout the MCP server with try-catch blocks around all Neovim RPC calls, connection state validation, and graceful error reporting. The NeovimManager singleton maintains connection state and automatically reconnects on socket failures. Errors are caught at the RPC layer and returned as structured error responses with error codes and messages, preventing cascading failures.

Implements vim_edit tool that performs targeted text modifications using Neovim's native buffer API with line and column precision. Supports insertion, deletion, and replacement operations on specific line ranges, using Neovim's buffer_set_lines RPC method to atomically update content. The tool validates line numbers and handles edge cases (empty buffers, out-of-range lines) through Neovim's built-in error handling.

Implements vim_command tool that executes arbitrary Vim commands (e.g., :set, :substitute, :normal) through Neovim's command RPC interface and captures output. The tool translates MCP requests into Neovim's nvim_command or nvim_exec RPC calls, enabling access to Neovim's full command language without requiring direct shell execution or keystroke simulation.

Implements vim_search and vim_search_replace tools that perform pattern-based text search and replacement using Neovim's native search capabilities. vim_search uses Neovim's search API to find patterns and return line numbers and context, while vim_search_replace executes :substitute commands with optional flags (case-insensitive, global, etc.). Both tools leverage Neovim's regex engine rather than implementing custom pattern matching.

Implements vim_buffer_switch tool that changes the active buffer in Neovim using the buffer number or name, and vim_file_open that opens files by path. Both tools use Neovim's native buffer management RPC calls (nvim_set_current_buf, nvim_command for :edit) to navigate the editor state. The nvim://buffers resource provides the list of available buffers for navigation decisions.

Implements vim_buffer_save tool that writes buffer content to disk using Neovim's :write command, and vim_file_open that creates new buffers for files. The tools leverage Neovim's native file I/O and buffer management rather than implementing custom file writing. vim_buffer_save respects Neovim's file format settings and handles encoding automatically.

Exposes nvim://session resource that provides current editor session metadata including active buffer, cursor position, window layout, and editor mode. The resource is populated by querying Neovim's current state via RPC calls (nvim_get_current_buf, nvim_win_get_cursor, nvim_get_mode) and returns structured JSON. This enables MCP clients to understand editor context without making separate tool calls.

Implements vim_grep tool that performs pattern-based search across multiple buffers or files using Neovim's :grep command (which delegates to external grep/ripgrep). The tool executes :grep with a pattern and optional file filter, captures results, and returns structured match data with file paths, line numbers, and context. Results are parsed from Neovim's quickfix list.

Implements vim_record_macro and vim_playback_macro tools that enable recording and executing Vim macros through MCP. vim_record_macro captures a sequence of Vim commands into a named register, while vim_playback_macro executes a recorded macro a specified number of times. Both tools use Neovim's register management RPC API (nvim_get_register, nvim_set_register) to store and retrieve macro content.