Nvim MCP Server

Neovim MCP服务器

Neovim的模型上下文协议（MCP）服务器的Ruby实现。此服务器允许LLM（大型语言模型）通过模型上下文协议与Neovim交互，提供查询缓冲区和在编辑器中执行操作的功能。

什么是MCP？

模型上下文协议（MCP）是人工智能模型与其环境交互的标准化方式。它为模型定义了一种结构化方法，用于在交互过程中请求和使用工具、访问资源和维护上下文。

此Neovim MCP服务器实现了MCP规范，使AI模型能够访问Neovim进行缓冲区分析、文件探索和编辑辅助。

特性

• 连接到正在运行的Neovim实例
• 跨多个Neovim会话的查询缓冲区
• 遵循模型上下文协议标准
• 与LLM客户无缝集成

安装

安装gem：

gem install nvim-mcp-server

安装后 nvim-mcp-server 可执行文件将在您的PATH中可用。

配置

Neovim MCP服务器遵循XDG基本目录规范的配置文件：

• 在 macOS 上： $XDG_CONFIG_HOME/nvim-mcp 或 ~/.config/nvim-mcp 如果XDG_CONFIG_HOME未设置
• 在Linux上： $XDG_CONFIG_HOME/nvim-mcp 或 ~/.config/nvim-mcp 如果XDG_CONFIG_HOME未设置
• 在Windows上： %APPDATA%\nvim-mcp

服务器将在首次运行时自动创建这些目录和日志文件。

用法

启动服务器

Neovim MCP服务器可以在两种模式下运行：

1. STDIO模式（默认）：通过标准输入/输出进行通信，以便与Claude Desktop等客户端直接集成。
2. HTTP模式：作为具有JSON-RPC和服务器发送事件（SSE）端点的HTTP服务器运行。

# 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

在HTTP模式下运行时，服务器提供两个端点：

• JSON-RPC端点： `http://localhost:

/mcp/messages`

• SSE 端点 ： `http://localhost:

/mcp/sse`

记录选项

默认情况下，服务器会登录到配置目录中的一个文件。您可以使用以下选项自定义日志记录：

# Set the log level (debug, info, error)
nvim-mcp-server --log-level debug

Claude桌面集成

Neovim MCP服务器可以通过手动配置集成与Claude Desktop一起使用。

直接配置

1. 为您的平台创建适当的配置目录：

- macOS： $XDG_CONFIG_HOME/nvim-mcp 或 ~/.config/nvim-mcp 如果XDG_CONFIG_HOME未设置 - Linux： $XDG_CONFIG_HOME/nvim-mcp 或 ~/.config/nvim-mcp 如果XDG_CONFIG_HOME未设置 - 窗户： %APPDATA%\nvim-mcp

1. 查找或创建Claude Desktop配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

1. 添加或更新MCP服务器配置：

{
  "mcpServers": {
    "nvimMcpServer": {
      "command": "ruby",
      "args": ["/full/path/to/nvim-mcp-server/exe/nvim-mcp-server"] 
    }
  }
}

1. 重新启动Claude Desktop以应用更改。

Ruby版本管理器用户

Claude Desktop使用系统的默认Ruby环境启动MCP服务器，绕过版本管理器初始化（例如rbenv、RVM）。MCP服务器需要使用与安装时相同的Ruby版本，因为使用不兼容的Ruby版本时可能会发生MCP服务器启动失败。

如果你使用的是像rbenv这样的Ruby版本管理器，你可以创建一个指向Ruby垫片的符号链接，以确保使用正确的版本：

sudo ln -s /home/your_user/.rbenv/shims/ruby /usr/local/bin/ruby

将“/home/your_user/.rbenv/shims/ruby”替换为ruby垫片的实际路径。

使用MCP代理（高级）

Claude Desktop和许多其他LLM客户端仅支持STDIO模式通信，但您可能希望使用服务器的HTTP/SSE功能。MCP代理可以弥合这一差距：

1. 以HTTP模式启动Neovim MCP服务器：

nvim-mcp-server --mode http

1. 安装并运行MCP代理。有几种不同语言的实现。MCP代理允许仅支持STDIO通信的客户端通过HTTP SSE进行通信。以下是一个使用基于JavaScript的MCP代理的示例：

# Install the Node.js based MCP proxy
npm install -g mcp-remote

# Run the proxy, pointing to your running Neovim MCP Server
npx mcp-remote http://localhost:6030/mcp/sse

1. 将Claude Desktop（或其他LLM客户端）配置为使用代理，而不是直接连接到服务器：

{
  "mcpServers": {
    "nvimMcpServer": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:6030/mcp/sse"]
    }
  }
}

此设置允许仅STDIO的客户端通过代理与Neovim MCP服务器通信，在保持客户端兼容性的同时受益于HTTP/SSE功能。

Neovim配置

为了使MCP服务器正常工作，您的Neovim实例需要使用一个命名套接字启动：

nvim --listen /tmp/nvim-project_name.sock

您可以通过在Neovim配置中添加以下内容来实现自动化：

-- In your init.lua
local project_name = vim.fn.fnamemodify(vim.fn.getcwd(), ':t')
vim.fn.serverstart('/tmp/nvim-' .. project_name .. '.sock')

服务器的工作原理

Neovim MCP服务器使用以下任一方式实现模型上下文协议：

• STDIO模式：从标准输入读取JSON-RPC 2.0请求，并返回对标准输出的响应。
• HTTP模式：为JSON-RPC 2.0请求和服务器发送事件提供HTTP端点。

服务器通过位于以下位置的Unix套接字与Neovim实例通信 /tmp/nvim-{project_name}.sock这允许服务器与运行不同项目的多个Neovim实例进行交互。

可用工具

服务器提供以下与Neovim交互的工具：

1. get_project_buffers

说明： 检索当前在Neovim中打开的属于特定项目的文件列表。此工具使用位于/tmp/nvim-{project_name}.sock的套接字文件连接到正在运行的Neovim实例，并查询所有打开的缓冲区。然后，它会过滤缓冲区，使其仅包含路径中包含项目名称的文件。这对于确定用户当前在特定项目中编辑哪些文件、识别活动开发区域或跨多个文件跟踪工作上下文非常有用。该工具优雅地处理连接失败，并返回完整的绝对文件路径。

参数：

• project_name：（String，必填）用于筛选缓冲区的项目目录的名称。这应该与要检索的缓冲区的文件路径中的目录名匹配。例如，如果您的项目位于“/home/user/projects/my app”，您将使用“my app”作为项目名称。该工具还将使用此名称在/tmp/nvim-{project_name}.sock中定位Neovim套接字。

例子

Can you show me which files I have open in my "my-project" Neovim instance?

I'd like to know what files I'm currently working on in the "blog" project.

List all the buffers for the "nvim-mcp-server" project.

测试和调试

测试和调试Neovim MCP服务器的最简单方法是使用MCP Inspector，这是一种专门为测试和调试MCP服务器而设计的开发工具。

要将MCP检查器与Neovim MCP服务器一起使用：

# Install and run MCP Inspector with your Neovim MCP Server
npm -g install @modelcontextprotocol/inspector

npx @modelcontextprotocol/inspector /path/to/nvim-mcp-server

这将：

1. 以HTTP模式启动Neovim MCP服务器
2. 在浏览器中启动MCP Inspector UI（默认端口：6274）

在MCP检查器UI中，您可以：

• 查看所有可用工具
• 以交互方式执行工具调用
• 查看请求和响应详细信息
• 实时调试问题

许可证

这个Neovim MCP服务器是在MIT许可证下发布的，这是一个允许自由使用、修改、分发和私人使用的开源许可证。

版权所有（c）2025马里奥·阿尔贝托·查韦斯·卡德纳斯

特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人在不受限制的情况下处理软件的权限，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，以及允许获得软件的人这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或实质部分中。

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而产生或与之相关的任何索赔、损害赔偿或其他责任承担责任，无论是在合同、侵权或其他诉讼中。

贡献

欢迎在GitHub上提交Bug报告和拉取请求，网址为 .