Neovim

community

other

An MCP Server for your Neovim session.

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.