星战科技xingzhan.cloud
返回市场
nvim-mcp服务器

nvim-mcp服务器

作者：maquina-app13 星标更新：2025-07-27
安装使用来源：spider==github.com

项目介绍

Neovim MCP 服务器

Neovim 的 Model Context Protocol (MCP) 服务器的 Ruby 实现。此服务器允许大型语言模型（LLMs）通过 Model Context Protocol 与 Neovim 进行交互，提供查询缓冲区并在编辑器中执行操作的能力。

什么是 MCP？

Model Context Protocol (MCP) 是一种标准化的方式，使 AI 模型能够与其环境进行交互。它定义了一种结构化的方法，让模型请求并使用工具，访问资源，并在交互过程中维护上下文。

这个 Neovim MCP 服务器实现了 MCP 规范，为 AI 模型提供了访问 Neovim 的能力，用于缓冲区分析、文件探索和编辑辅助。

特性

  • 连接到正在运行的 Neovim 实例
  • 查询多个 Neovim 会话中的缓冲区
  • 遵循 Model Context Protocol 标准
  • 无缝集成到 LLM 客户端

安装

安装 gem：

gem install nvim-mcp-server

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

配置

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

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

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

使用方法

启动服务器

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

  1. STDIO 模式（默认）：通过标准输入/输出进行通信，直接集成到像 Claude Desktop 这样的客户端。
  2. HTTP 模式：作为带有 JSON-RPC 和 Server-Sent Events (SSE) 端点的 HTTP 服务器运行。
# 以默认的 STDIO 模式启动
nvim-mcp-server

# 在默认端口（6030）上以 HTTP 模式启动
nvim-mcp-server --mode http

# 在自定义端口上以 HTTP 模式启动
nvim-mcp-server --mode http -p 8080

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

  • JSON-RPC 端点：http://localhost:<port>/mcp/messages
  • SSE 端点：http://localhost:<port>/mcp/sse

日志选项

服务器默认将日志记录到配置目录中的文件。你可以通过以下选项自定义日志：

# 设置日志级别（debug, info, error）
nvim-mcp-server --log-level debug

Claude Desktop 集成

Neovim MCP 服务器可以通过手动配置集成到 Claude Desktop。

直接配置

  1. 创建适合你平台的配置目录：

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

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

    • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux：~/.config/Claude/claude_desktop_config.json
    • Windows：%APPDATA%\Claude\claude_desktop_config.json

  3. 添加或更新 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 shim 的符号链接，以确保使用正确的版本：

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

请将 "/home/your_user/.rbenv/shims/ruby" 替换为你实际的 Ruby shim 路径。

使用 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 代理的例子：
# 安装基于 Node.js 的 MCP 代理
npm install -g mcp-remote

# 运行代理，指向正在运行的 Neovim MCP 服务器
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 配置中来自动化这一点：

-- 在你的 init.lua 中
local project_name = vim.fn.fnamemodify(vim.fn.getcwd(), ':t')
vim.fn.serverstart('/tmp/nvim-' .. project_name .. '.sock')

服务器的工作原理

Neovim MCP 服务器通过以下方式实现 Model Context Protocol：

  • STDIO 模式：从标准输入读取 JSON-RPC 2.0 请求，并将响应返回到标准输出。
  • HTTP 模式：提供用于 JSON-RPC 2.0 请求和 Server-Sent Events 的 HTTP 端点。

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

提供的工具

服务器提供了以下工具用于与 Neovim 交互：

1. get_project_buffers

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

参数：

  • project_name：(字符串，必需) 用于筛选缓冲区的项目目录名称。这应该匹配你想要检索的缓冲区文件路径中的目录名称。例如，如果项目位于 '/home/user/projects/my-app'，则应使用 'my-app' 作为 project_name。该工具还将使用此名称来定位 Neovim 套接字 /tmp/nvim-{project_name}.sock。

示例

你能显示我在 "my-project" Neovim 实例中打开了哪些文件吗？

我想知道我现在在 "blog" 项目中正在编辑哪些文件。

列出 "nvim-mcp-server" 项目的所有缓冲区。

测试和调试

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

要使用 MCP Inspector 与 Neovim MCP 服务器一起：

# 安装并运行 MCP Inspector 与你的 Neovim MCP 服务器
npm -g install @modelcontextprotocol/inspector

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

这将：

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

在 MCP Inspector UI 中，你可以：

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

许可证

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

版权所有 (c) 2025 Mario Alberto Chávez Cárdenas

特此授予任何人获得此软件及其相关文档文件副本的人（以下简称“软件”），在不受限制的情况下使用、复制、修改、合并、出版、分发、再许可和/或出售软件副本的权利，并允许向其提供软件的人这样做，但需遵守以下条件：

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

软件按“原样”提供，不附带任何形式的保证，无论是明示的还是默示的，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人都不对因软件或其使用或其它交易而产生的任何索赔、损害或其他责任承担任何责任，无论是在合同行为、侵权行为或其他行为中。

贡献

欢迎在 GitHub 上提交错误报告和拉取请求：https://github.com/maquina-app/nvim-mcp-server。