MCP Neovim Server

🚀 Neovim MCP Server

This is a proof-of-concept project for integrating Claude Desktop (or other clients) with Neovim via the Model Context Protocol (MCP). It uses the official neovim/node-client JavaScript library to create a lightweight AI text assistance layer for code or general purposes.

✨ Features

• If you expose a socket file when starting Neovim, e.g., --listen /tmp/nvim, the server can connect to your Neovim instance.
• View the currently open buffers.
• Get the cursor position, mode, and file name.
• Execute Neovim commands and optional shell commands (through Neovim).
• Perform edits using insert or replace methods.

📚 Documentation

Resources

• nvim://session: The current Neovim text editing session.
• nvim://buffers: A list of all open buffers in the current Neovim session, including metadata such as modification status, syntax, and window ID.

Tools

• vim_buffer:
  • The content of the current VIM text editor buffer, showing line numbers.
  • Input filename (string).
  • If the file name is ignored, it returns a numbered line string of the content of the current active buffer.
• vim_command:
  • Send commands to VIM for navigation, targeted editing, and line deletion.
  • Input command (string).
  • First, run a Neovim command through nvim.replaceTermcodes. If the input contains multiple commands, they can be separated by line breaks.
  • Returns the content of 'nvim:errmsg' in case of an error.
• vim_status:
  • Get the status of the VIM editor.
  • The status includes the cursor position, mode, file name, visual selection, window layout, current tab, marks, registers, and working directory.
• vim_edit:
  • Edit lines using insert, replace, or full-replace methods.
  • Input startLine (number), mode ("insert" | "replace" | "replaceAll"), lines (string).
  • Insert mode inserts lines at startLine.
  • Replace mode replaces lines starting from startLine.
  • Full-replace mode replaces the entire buffer content.
• vim_window:
  • Manage Neovim windows (split, vertical split, show only, close).
  • Input command (string: "split", "vsplit", "only", "close", "wincmd h/j/k/l").
  • Allows window management operations.
• vim_mark:
  • Set a mark at a specific position.
  • Input mark (string: a - z), line (number), column (number).
  • Sets a named mark at the specified position.
• vim_register:
  • Set the content of a register.
  • Input register (string: a - z or '"'), content (string).
  • Manages register content.
• vim_visual:
  • Create a visual selection.
  • Input startLine (number), startColumn (number), endLine (number), endColumn (number).
  • Sets the visual selection range.

Through the above tools, users can easily interact with Neovim to achieve various editing and management functions.

⚠️ Important Note

This project aims to provide an interface for AI tools like Claude to integrate more naturally with Neovim. Although Neovim is already very powerful, extending its functionality through the MCP protocol can further improve development efficiency and user experience.

💡 Usage Tip

• Ensure that Neovim and related plugins are correctly installed and configured during use.
• Additional configuration or script support may be required for advanced features.
• If you encounter any problems, refer to the project documentation or community resources for help.

📄 License

This project is licensed under the MIT License. Please see the LICENSE file for details.

👥 Contribution

Any contributions are welcome! Whether it's code fixes, feature additions, or documentation improvements, we welcome your participation.

Please read our CONTRIBUTING.md file before proposing changes to understand how to contribute effectively to the project.