📌Overview

Purpose: To provide an integration between Claude Desktop (or any client) and Neovim utilizing the Model Context Protocol (MCP), enabling AI-assisted text editing.

Overview: The Neovim MCP Server serves as a lightweight AI text assistance layer that interacts with Neovim editor features. It operates through the official neovim/node-client JavaScript library, leveraging Vim's commands and workflows for enhanced coding support.

Key Features:

• Socket Connection: Connects to an existing Neovim instance using a socket file, facilitating real-time editing and commands.

• Buffer Management: Allows viewing and managing current buffers, fetching details such as cursor position, mode, and filename.

• Command Execution: Enables running both Vim and optional shell commands for navigation, editing, and manipulation directly from the client.

• Editing Capabilities: Supports inserting, replacing, or entirely replacing text in buffers, based on user input.

• Window Manipulation: Provides tools for managing Neovim windows, including splitting, closing, and navigating them.

---

Neovim MCP Server

A proof of concept integration between Claude Desktop (or any client) and Neovim using Model Context Protocol (MCP) and the official neovim/node-client JavaScript library. This server uses Vim's native text editing commands and workflows to create a lightweight AI text assistance layer.

Features

• Connects to your Neovim instance via a socket file (e.g., --listen /tmp/nvim)
• Views current buffers
• Gets cursor location, mode, and file name
• Runs Vim commands and shell commands through Vim
• Edits using insert or replacement modes

API

Resources

• nvim://session: Current Neovim text editor session
• nvim://buffers: List of all open buffers with metadata

Tools

• vim_buffer: Current Vim buffer with numbered lines
• vim_command: Send commands for navigation and editing
• vim_status: Get the status of the Vim editor, including cursor position and filename
• vim_edit: Edit lines in the Vim editor (insert, replace, replaceAll)
• vim_window: Manipulate Neovim windows (split, close, navigate)
• vim_mark: Set a mark at a specific position
• vim_register: Manage the content of a register
• vim_visual: Make a visual selection

Limitations

• This is a proof of concept for the Model Context Protocol; use at your own risk.
• May have compatibility issues with custom Neovim configurations.
• Error handling is basic.
• Command input may not always work as expected.

Configuration

Environment Variables

• ALLOW_SHELL_COMMANDS: Set to 'true' to enable shell command execution (default is false for security).
• NVIM_SOCKET_PATH: Path of your Neovim socket (defaults to '/tmp/nvim').

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

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

License

This MCP server is licensed under the MIT License, allowing free use, modification, and distribution. For details, refer to the LICENSE file in the project repository.