Neovim Integration MCP server

This MCP server provides integration between Claude Desktop (or any MCP client) and Neovim, creating a lightweight AI text assistance layer. It allows Claude to view and edit your Neovim buffers, execute vim commands, and interact with your editor session using the Model Context Protocol.

Installation

To use the Neovim MCP Server, you'll need to:

1. Ensure Neovim is running with an exposed socket
2. Configure Claude Desktop to use the MCP server

Starting Neovim with a Socket

When launching Neovim, use the --listen flag to expose a socket:

nvim --listen /tmp/nvim

Configuring Claude Desktop

Add the following to your claude_desktop_config.json file:

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

Configuration Options

Environment Variables

You can customize the server behavior with these environment variables:

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

Usage

Once configured, Claude can interact with your Neovim session through several tools:

Viewing Buffer Content

Claude can see the current buffer's content, including line numbers, using the vim_buffer tool.

Executing Vim Commands

Claude can run vim commands using the vim_command tool. For example:

• Navigation: j, k, gg, G, /pattern
• Edits: dd, yy, p
• Mode changes: i, v, ESC

Getting Editor Status

Claude can check your cursor position, current mode, filename, and other status information using vim_status.

Making Edits

Claude can insert or replace text using the vim_edit tool with parameters:

• startLine: Where to begin editing
• mode: "insert" or "replace"
• lines: The text content to insert/replace

Window Management

Claude can manipulate Neovim windows with vim_window using commands like:

• split
• vsplit
• close
• wincmd h/j/k/l (for navigation)

Working with Marks and Registers

Claude can set marks and modify registers using vim_mark and vim_register tools.

Visual Selections

Claude can create visual selections using the vim_visual tool by specifying start and end positions.

Limitations

Be aware that this is a proof of concept with some limitations:

• It may not work well with custom Neovim configurations
• Error handling is limited
• Claude may occasionally format vim commands incorrectly

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.