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 ```bash gem install nvim-mcp-server ``` ### 2. Configure Neovim Add to your `init.lua` to start the RPC server: ```lua -- Start the Neovim RPC server on a socket vim.fn.serverstart('/tmp/nvim-mcp.sock') ``` Or start Neovim with a socket: ```bash nvim --listen /tmp/nvim-mcp.sock ``` ### 3. Configure Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "nvimMcpServer": { "command": "nvim-mcp-server", "args": ["--socket", "/tmp/nvim-mcp.sock"] } } } ``` --- ## Available Tools The server provides 2 tools for buffer management. | Tool | Description | |------|-------------| | `get_project_buffers` | Get contents of all open buffers | | `update_buffer` | Update a buffer with new content | ### 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: ```bash nvim-mcp-server --socket /tmp/nvim-mcp.sock ``` ### HTTP Mode For HTTP endpoints with JSON-RPC and SSE: ```bash 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)** ```lua -- Always start the socket server vim.fn.serverstart('/tmp/nvim-mcp.sock') ``` **Option 2: Shell alias** ```bash alias nvim='nvim --listen /tmp/nvim-mcp.sock' ``` **Option 3: Per-session** ```bash nvim --listen /tmp/nvim-mcp.sock ``` ### Multiple Neovim Instances For multiple Neovim instances, use unique socket paths: ```lua -- 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: ```bash nvim-mcp-server --socket /tmp/nvim-mcp-12345.sock ``` --- ## Ruby Version Manager Users Claude Desktop bypasses version manager initialization. Use the Ruby shim path: ```json { "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: ```bash 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: ```bash # Should show the socket file ls -la /tmp/nvim-mcp.sock ``` From within Neovim, verify the server address: ```vim :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

GitHub Repository

Source code, issues, and contribution guidelines.

Rails MCP Server

Analyze models, routes, and schemas in your Rails projects.