Neovim MCP Server

MCP (Model Context Protocol) server that integrates Neovim buffers with Claude Code, enabling seamless buffer awareness and real-time updates.

Features

Resources (Auto-available Context)

• nvim://current-buffer - Currently active buffer with path and content

• nvim://open-buffers - List of all open buffers with metadata

Tools (Claude Can Invoke)

• list_nvim_buffers() - List all open buffers in nvim instances running in current directory

• get_current_buffer() - Get the currently active buffer

• get_buffer_content(path) - Get content of a specific buffer by path

• update_buffer(path, content) - Update buffer content directly in nvim (changes appear immediately!)

Installation

No installation required! Use npx to run the server directly.

Setup with Claude Code

Add this MCP server to your Claude Code configuration:

File: ~/.claude/claude_desktop_config.json (or your Claude Code config file)

Usage

Once configured, the MCP server will automatically:

1. Detect Neovim instances running in the current directory

2. Expose buffer context to Claude via resources

3. Enable buffer operations via tools

Example Workflows

1. Refactor Current File

2. Check Open Buffers

3. Update Specific Buffer

How It Works

1. Discovery: Uses $TMPDIR to find nvim socket files

2. Filtering: Only connects to nvim instances running in the current directory

3. RPC Communication: Uses the neovim npm package to communicate via msgpack-rpc

4. MCP Integration: Exposes nvim buffers as MCP resources and tools

Socket Discovery

The server finds nvim sockets using:

• macOS: $TMPDIR/nvim*/0 (typically /var/folders/.../T/nvim*/0)

• Linux: $TMPDIR/nvim*/0 or /tmp/nvim*/0

• Falls back to /tmp if $TMPDIR is not set

Benefits

Real-Time Updates

Traditional:

With MCP:

Context Awareness

Claude automatically knows:

• Which file you're currently editing

• All files you have open

• Can make changes directly in your editor

Seamless Integration

• No file writes needed (updates are in-memory)

• Works with unsaved buffers

• Normal nvim undo/redo works

• Triggers autocmds (LSP, linting, etc.)

Troubleshooting

No Neovim instances found

• Make sure you're running the command from the same directory as your nvim instance

• Check that nvim is running: ps aux | grep nvim

• Verify socket exists: ls $TMPDIR/nvim*/0

Buffer updates not appearing

• Ensure the buffer path matches exactly (use absolute paths)

• Check that the buffer is listed: :ls in nvim

• Verify the MCP server has permissions to access the socket

MCP server not connecting

• Restart Claude Code after adding the MCP configuration

• Check Claude Code logs for errors

• Verify the path in the config is absolute and correct

Development

Test the server manually:

The server communicates via stdio, so you'll need an MCP client (like Claude Code) to interact with it properly.

Debug mode:

The server logs errors to stderr, which you can see in Claude Code's MCP server logs.

Requirements

• Node.js 16+

• Neovim with RPC support (any recent version)

• Running nvim instance in the directory where you invoke Claude

License

MIT