MCP server for exposing Neovim buffers to AI agents like Claude Code
npm install nvim-mcp-serverMCP (Model Context Protocol) server that integrates Neovim buffers with Claude Code, enabling seamless buffer awareness and real-time updates.
nvim://current-buffer - Currently active buffer with path and contentnvim://open-buffers - List of all open buffers with metadatalist_nvim_buffers() - List all open buffers in nvim instances running in current directoryget_current_buffer() - Get the currently active bufferget_buffer_content(path) - Get content of a specific buffer by pathupdate_buffer(path, content) - Update buffer content directly in nvim (changes appear immediately!)open_file(path) - Open a file in nvim (useful after creating new files)reload_buffer(path) - Reload a buffer from diskreload_all_buffers() - Check and reload all buffers that changed on diskRun the following command in your terminal:
``bash`
claude mcp add --transport stdio nvim -- npx nvim-mcp-server
This will automatically add the server to your ~/.claude.json configuration.
Alternatively, manually edit ~/.claude.json:
`json`
{
"mcpServers": {
"nvim": {
"command": "npx",
"args": ["nvim-mcp-server"]
}
}
}
After adding the configuration, restart Claude Code for changes to take effect.
Check that the server is configured correctly:
`bash`
claude mcp list
Or use /mcp within Claude Code to check server status.
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
#### 1. Refactor Current File
`
You: "Refactor the current file to use async/await"
Claude:
- Reads nvim://current-buffer resource automatically
- Sees you're working on src/api.js
- Refactors the code
- Calls update_buffer() to push changes to nvim
- Changes appear instantly in your editor!
`
#### 2. Check Open Buffers
`
You: "What files do I have open in nvim?"
Claude:
- Calls list_nvim_buffers() tool
- Shows you all open buffers
`
#### 3. Update Specific Buffer
`
You: "Add error handling to src/utils.js"
Claude:
- Calls get_buffer_content("src/utils.js")
- Adds error handling
- Calls update_buffer() to apply changes
- You see updates in nvim immediately
`
#### 4. Create and Open New File
`
You: "Create a new component called Button.jsx"
Claude:
- Creates the file using Write tool
- Calls open_file("src/components/Button.jsx")
- File opens in your nvim automatically
- You can continue editing right away!
`
1. Discovery: Uses $TMPDIR to find nvim socket filesneovim
2. Filtering: Only connects to nvim instances running in the current directory
3. RPC Communication: Uses the npm package to communicate via msgpack-rpc
4. MCP Integration: Exposes nvim buffers as MCP resources and tools
The server finds nvim sockets using:
- macOS: $TMPDIR/nvim/0 (typically /var/folders/.../T/nvim/0)$TMPDIR/nvim/0
- Linux: or /tmp/nvim/0/tmp
- Falls back to if $TMPDIR is not set
Claude writes to file → You reload in nvim
`With MCP:
`
Claude updates buffer via RPC → Changes appear instantly
`$3
Claude automatically knows:
- Which file you're currently editing
- All files you have open
- Can make changes directly in your editor$3
- No file writes needed (updates are in-memory)
- Works with unsaved buffers
- Normal nvim undo/redo works
- Triggers autocmds (LSP, linting, etc.)Troubleshooting
$3
- 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$3
- 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$3
- Restart Claude Code after adding the MCP configuration
- Check Claude Code logs for errors
- Verify the path in the config is absolute and correctDevelopment
$3
`bash
node index.js
`The server communicates via stdio, so you'll need an MCP client (like Claude Code) to interact with it properly.
$3
The server logs errors to stderr, which you can see in Claude Code's MCP server logs.$3
`bash
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:ui # Interactive UI
npm run test:coverage # With coverage report
`Publishing
The project includes automated release scripts for publishing to npm.
$3
- Clean git working directory
- Tests must pass
- npm authentication configured (npm login)$3
Patch release (1.0.0 → 1.0.1):
`bash
npm run release:patch
`Minor release (1.0.0 → 1.1.0):
`bash
npm run release:minor
`Major release (1.0.0 → 2.0.0):
`bash
npm run release:major
`Specific version:
`bash
npm run release 1.2.3
``If any step fails, the script will abort and rollback changes.
- Node.js 16+
- Neovim with RPC support (any recent version)
- Running nvim instance in the directory where you invoke Claude
MIT