Neovim MCP Server — Maquina

A Ruby implementation of a Model Context Protocol (MCP) server for Neovim integration. Coordinate file changes between your editor and AI assistants by reading and updating Neovim buffers directly.

What is MCP?

The Model Context Protocol (MCP) is a standardized way for AI models to interact with their environment. It defines how models request and use tools, access resources, and maintain context.

The Neovim MCP Server exposes your editor’s buffers to AI assistants, enabling them to read file contents and push changes directly into your editing session.

Features

• Read buffer contents from Neovim
• Update buffer contents with new code
• Coordinate changes between AI assistants and your editor
• Works with Claude Desktop and other MCP clients
• STDIO and HTTP server modes

Quick Start

1. Install the Gem

gem install nvim-mcp-server

2. Configure Neovim

Add to your init.lua to start the RPC server:

-- Start the Neovim RPC server on a socket
vim.fn.serverstart('/tmp/nvim-mcp.sock')

Or start Neovim with a socket:

nvim --listen /tmp/nvim-mcp.sock

3. Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "nvimMcpServer": {
      "command": "nvim-mcp-server",
      "args": ["--socket", "/tmp/nvim-mcp.sock"]
    }
  }
}

Available Tools

The server provides 2 tools for buffer management.

Get Project Buffers

Returns the contents of all buffers currently open in Neovim:

get_project_buffers()

Response includes file paths and their contents, allowing AI assistants to understand your current working context.

Update Buffer

Updates a specific buffer with new content:

update_buffer(file_path: "/path/to/file.rb", content: "new content here")

The changes appear immediately in Neovim, ready for you to review, modify, or save.

Server Modes

STDIO Mode (Default)

For direct integration with Claude Desktop:

nvim-mcp-server --socket /tmp/nvim-mcp.sock

HTTP Mode

For HTTP endpoints with JSON-RPC and SSE:

nvim-mcp-server --mode http --socket /tmp/nvim-mcp.sock
nvim-mcp-server --mode http --socket /tmp/nvim-mcp.sock -p 8080

Endpoints:

• JSON-RPC: http://localhost:6030/mcp/messages
• SSE: http://localhost:6030/mcp/sse

Neovim Configuration

Socket Setup

The MCP server communicates with Neovim via RPC over a Unix socket. Configure Neovim to listen:

Option 1: In init.lua (recommended)

-- Always start the socket server
vim.fn.serverstart('/tmp/nvim-mcp.sock')

Option 2: Shell alias

alias nvim='nvim --listen /tmp/nvim-mcp.sock'

Option 3: Per-session

nvim --listen /tmp/nvim-mcp.sock

Multiple Neovim Instances

For multiple Neovim instances, use unique socket paths:

-- In init.lua
local socket_path = '/tmp/nvim-mcp-' .. vim.fn.getpid() .. '.sock'
vim.fn.serverstart(socket_path)
print('Neovim socket: ' .. socket_path)

Then specify the socket when starting the MCP server:

nvim-mcp-server --socket /tmp/nvim-mcp-12345.sock

Ruby Version Manager Users

Claude Desktop bypasses version manager initialization. Use the Ruby shim path:

{
  "mcpServers": {
    "nvimMcpServer": {
      "command": "/home/your_user/.rbenv/shims/ruby",
      "args": [
        "/path/to/nvim-mcp-server/exe/nvim-mcp-server",
        "--socket",
        "/tmp/nvim-mcp.sock"
      ]
    }
  }
}

Testing and Debugging

Use MCP Inspector to test the server:

npm -g install @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector nvim-mcp-server --socket /tmp/nvim-mcp.sock

The Inspector UI lets you:

• See available tools
• Execute tool calls interactively
• View request and response details
• Debug issues in real-time

Verify Neovim Socket

Check that Neovim is listening:

# Should show the socket file
ls -la /tmp/nvim-mcp.sock

From within Neovim, verify the server address:

:echo v:servername

Use Cases

Code Review Workflow

1. Open files in Neovim
2. Ask Claude to review the open buffers
3. Claude reads via get_project_buffers
4. Claude suggests changes via update_buffer
5. Review changes in Neovim before saving

AI-Assisted Editing

Combine with other MCP servers for powerful workflows:

• Use Rails MCP Server to understand your codebase
• Use Neovim MCP Server to apply changes directly to your editor
• Review and refine changes before committing

Next Steps