Neovim MCP Server
A Ruby implementation of a Model Context Protocol (MCP) server for Neovim. This server allows LLMs (Large Language Models) to interact with Neovim through the Model Context Protocol, providing capabilities to query buffers and perform operations within the editor.
What is MCP?
The Model Context Protocol (MCP) is a standardized way for AI models to interact with their environment. It defines a structured method for models to request and use tools, access resources, and maintain context during interactions.
This Neovim MCP Server implements the MCP specification to give AI models access to Neovim for buffer analysis, file exploration, and editing assistance.
Features
- Connect to running Neovim instances
- Query buffers across multiple Neovim sessions
- Update and save buffers with new content
- Follow the Model Context Protocol standard
- Seamless integration with LLM clients
Installation
Install the gem:
gem install nvim-mcp-server
After installation, the nvim-mcp-server executable will be available in your PATH.
Configuration
The Neovim MCP Server follows the XDG Base Directory Specification for configuration files:
- On macOS:
$XDG_CONFIG_HOME/nvim-mcp or ~/.config/nvim-mcp if XDG_CONFIG_HOME is not set
- On Windows:
%APPDATA%\nvim-mcp
The server will automatically create these directories and a log file the first time it runs.
Usage
Starting the server
The Neovim MCP Server can run in two modes:
- STDIO mode (default): Communicates over standard input/output for direct integration with clients like Claude Desktop.
- HTTP mode: Runs as an HTTP server with JSON-RPC and Server-Sent Events (SSE) endpoints.
# Start in default STDIO mode
nvim-mcp-server
# Start in HTTP mode on the default port (6030)
nvim-mcp-server --mode http
# Start in HTTP mode on a custom port
nvim-mcp-server --mode http -p 8080
# Start in HTTP mode binding to all interfaces (for local network access)
nvim-mcp-server --mode http --bind-all
When running in HTTP mode, the server provides two endpoints:
- JSON-RPC endpoint:
http://localhost:<port>/mcp/messages
- SSE endpoint:
http://localhost:<port>/mcp/sse
Network Access (HTTP Mode)
By default, the HTTP server only binds to localhost for security. If you need to access the server from other machines on your local network (e.g., for testing with multiple devices), you can use the --bind-all flag:
# Allow access from any machine on your local network
nvim-mcp-server --mode http --bind-all
# With a custom port
nvim-mcp-server --mode http --bind-all -p 8080
When using --bind-all:
- The server binds to
0.0.0.0 instead of localhost
- Access is allowed from local network IP ranges (192.168.x.x, 10.x.x.x, 172.16.x.x)
- The server accepts connections from
.local domain names (e.g., my-computer.local)
- Security features remain active to prevent unauthorized access
Security Note: Only use --bind-all on trusted networks. The server includes built-in security features to validate origins and IP addresses, but exposing any service to your network increases the attack surface.
Logging Options
The server logs to a file in your config directory by default. You can customize logging with these options:
# Set the log level (debug, info, error)
nvim-mcp-server --log-level debug
Claude Desktop Integration
The Neovim MCP Server can be used with Claude Desktop by manually configuring the integration.
Direct Configuration
-
Create the appropriate config directory for your platform:
- macOS:
$XDG_CONFIG_HOME/nvim-mcp or ~/.config/nvim-mcp if XDG_CONFIG_HOME is not set
- Windows:
%APPDATA%\nvim-mcp
-
Find or create the Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
-
Add or update the MCP server configuration:
... [View full README on GitHub](https://github.com/maquina-app/nvim-mcp-server#readme)
