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 code or general purpose 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 will work if separated by newlines
  • 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 will insert lines at startLine
  • replace will replace lines starting at startLine
  • replaceAll will replace 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

• This is a quick proof of concept to experiment with Model Context Protocol. Use at your own risk.
• May not interact well with a custom neovim config!
• Error handling could be better.
• Sometimes Claude doesn’t get the vim command input just right.

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: Set to the 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. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.