📌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 leverages Vim's native text editing commands and workflows, which Claude already understands, to create a lightweight AI text assistance layer.

Features

• Connects to your nvim instance if you expose a socket file, for example --listen /tmp/nvim, when starting nvim
• Views your current buffers
• Gets cursor location, mode, file name
• Runs vim commands and optionally shell commands through vim
• Can make edits using insert or replacement

API

Resources

• nvim://session: Current neovim text editor session
• nvim://buffers: List of all open buffers in the current Neovim session with metadata including modified status, syntax, and window IDs

Tools

• vim_buffer
  Current VIM text editor buffer with line numbers shown
  Input filename (string)
  Filename is ignored, returns a string of numbered lines with the current active buffer content

• vim_command
  Send a command to VIM for navigation, spot editing, and line deletion
  Input command (string)
  Runs a vim command first passed through nvim.replaceTermcodes. Multiple commands separated by newlines allowed
  On error, 'nvim:errmsg' contents are returned

• vim_status
  Get the status of the VIM editor
  Status contains cursor position, mode, filename, visual selection, window layout, current tab, marks, registers, and working directory

• vim_edit
  Edit lines using insert, replace, or replaceAll in the VIM editor
  Input startLine (number), mode ("insert" | "replace" | "replaceAll"), lines (string)

  • insert inserts lines at startLine
  • replace replaces lines starting at startLine
  • replaceAll replaces the entire buffer contents

• vim_window
  Manipulate Neovim windows (split, vsplit, close, navigate)
  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 named marks at specified positions

• vim_register
  Set content of a register
  Input register (string: a-z or "), content (string)
  Manages register contents

• vim_visual
  Make a visual selection
  Input startLine (number), startColumn (number), endLine (number), endColumn (number)
  Creates visual mode selections

Using this simple set of tools, Claude can peer into your neovim session to answer questions as well as make edits to the buffer.

Limitations

• Proof of concept for Model Context Protocol; use at your own risk
• May not interact well with custom neovim configs
• Error handling could be improved
• Occasionally, vim command input may not be processed correctly by Claude

Configuration

Environment Variables

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

Usage with Claude Desktop

Add this 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. You are free to use, modify, and distribute the software, subject to the terms of the MIT License. See the LICENSE file in the project repository for details.