Neovim MCP Server

Neovim MCP 服务

使用 MCP 和官方的 neovim/node-client JavaScript 库，将 Claude Desktop（或任何 Model Context Protocol 客户端）连接到 Neovim。此服务利用 Vim 原生的文本编辑命令和工作流，这些命令和工作流是 Claude 已经熟悉的，从而打造轻量级的代码或通用 AI 文本辅助层。

功能

• 如果启动 nvim 时通过 --listen /tmp/nvim 等方式公开套接字文件，则连接到你的 nvim 实例
• 查看当前缓冲区并管理缓冲区切换
• 获取光标位置、模式、文件名、标记、寄存器和可视选择
• 运行 vim 命令，并可选择通过 vim 运行 shell 命令
• 支持使用插入、替换或 replaceAll 模式进行编辑
• 支持正则表达式的搜索和替换功能
• 支持与 quickfix 集成的项目范围 grep 搜索
• 全面的窗口管理
• 健康监控和连接诊断

API

资源

• nvim://session：当前 Neovim 文本编辑器会话
• nvim://buffers：当前 Neovim 会话中所有已打开缓冲区的列表，包含修改状态、语法和窗口 ID 等元数据

工具

核心工具

• vim_buffer
  • 获取带行号的缓冲区内容（支持 filename 参数）
  • 输入 filename（字符串，可选）- 按文件名获取指定缓冲区
  • 返回带行号的缓冲区内容
• vim_command
  • 向 VIM 发送用于导航、局部编辑和删除行的命令
  • 输入 command（字符串）
  • 使用 nvim.replaceTermcodes 运行 vim 命令。多个命令可用换行符分隔
  • 当 ALLOW_SHELL_COMMANDS=true 时，支持使用 ! 前缀运行 shell 命令
  • 出错时，返回 'nvim:errmsg' 的内容
• vim_status
  • 获取全面的 Neovim 状态
  • 返回光标位置、模式、文件名、带增强检测的可视选择、窗口布局、当前标签页、标记、寄存器、工作目录、LSP 客户端信息和插件检测结果
  • 增强的可视选择报告：检测可视模式类型（字符／行／块），提供准确的选择文本、起止位置以及上一次可视选择的标记
• vim_edit
  • 使用 insert、replace 或 replaceAll 模式编辑行
  • 输入 startLine（数字）、mode（"insert" | "replace" | "replaceAll"）、lines（字符串）
  • insert：在 startLine 处插入行
  • replace：替换从 startLine 开始的行
  • replaceAll：替换整个缓冲区内容
• vim_window
  • 操作 Neovim 窗口（分屏、垂直分屏、关闭、导航）
  • 输入 command（字符串："split"、"vsplit"、"only"、"close"、"wincmd h/j/k/l"）
• vim_mark
  • 在指定位置设置命名标记
  • 输入 mark（字符串：a-z）、line（数字）、column（数字）
• vim_register
  • 设置寄存器内容
  • 输入 register（字符串：a-z 或 "）、content（字符串）
• vim_visual
  • 创建可视模式选择
  • 输入 startLine（数字）、startColumn（数字）、endLine（数字）、endColumn（数字）

增强的缓冲区管理

• vim_buffer_switch
  • 按名称或编号切换缓冲区
  • 输入 identifier（字符串 | 数字）- 缓冲区名称或编号
• vim_buffer_save
  • 保存当前缓冲区，或保存到指定文件名
  • 输入 filename（字符串，可选）- 保存到指定文件
• vim_file_open
  • 将文件打开到新缓冲区
  • 输入 filename（字符串）- 要打开的文件

搜索和替换

• vim_search
  • 在当前缓冲区中搜索，支持正则表达式
  • 输入 pattern（字符串）、ignoreCase（布尔值，可选）、wholeWord（布尔值，可选）
• vim_search_replace
  • 使用高级选项查找和替换
  • 输入 pattern（字符串）、replacement（字符串）、global（布尔值，可选）、ignoreCase（布尔值，可选）、confirm（布尔值，可选）
• vim_grep
  • 使用 vimgrep 在整个项目中搜索，并将结果列入 quickfix 列表
  • 输入 pattern（字符串）、filePattern（字符串，可选）——要搜索的文件模式

高级工作流工具

• vim_macro
  • 录制、停止和播放 Vim 宏
  • 输入 action（"record" | "stop" | "play"）、register（字符串，a-z）、count（数字，可选）
• vim_tab
  • 完整的标签页管理
  • 输入 action（"new" | "close" | "next" | "prev" | "first" | "last" | "list"）、filename（字符串，可选）
• vim_fold
  • 代码折叠操作
  • 输入 action（"create" | "open" | "close" | "toggle" | "openall" | "closeall" | "delete"）、startLine/endLine（数字，用于创建折叠）
• vim_jump
  • 跳转列表导航
  • 输入 direction（"back" | "forward" | "list"）

系统工具

• vim_health
  • 检查 Neovim 连接健康状况和套接字状态

使用这套完整的 19 个工具，Claude 可以查看你的 Neovim 会话、导航缓冲区、执行搜索、编辑内容、录制宏、管理标签页和折叠，并使用标准 Neovim 功能处理完整的开发工作流。

提示词

• neovim_workflow：获取有关常见 Neovim 工作流的上下文帮助和指导，包括编辑、导航、搜索、缓冲区管理、窗口操作和宏的使用。提供分步说明，帮助你使用可用的 MCP 工具完成任务。

错误处理

该服务通过自定义错误类和一致的错误响应实现了全面的错误处理：

• NeovimConnectionError：套接字连接失败，并提供详细信息
• NeovimCommandError：命令执行失败，并提供命令上下文
• NeovimValidationError：输入验证失败

v0.5.2 新增：现在所有工具都包含稳健的 try-catch 错误处理，并以正确的 MCP 格式返回有意义的错误消息。功能包括连接健康监控、优雅的错误传递，以及可用于诊断问题的实用错误消息。

限制

• 可能无法与复杂的 Neovim 配置或插件良好交互
• 出于安全考虑，默认禁用 Shell 命令执行
• 需要套接字连接——无法与标准 Vim 配合使用

配置

环境变量

• ALLOW_SHELL_COMMANDS：设置为 'true' 以启用 Shell 命令执行（例如 !ls）。出于安全考虑，默认值为 false。
• NVIM_SOCKET_PATH：设置为 Neovim 套接字的路径。未指定时，默认为 '/tmp/nvim'。

安装

选项 1：DXT 包（推荐）

1. 从 Releases 下载最新的 .dxt 文件
2. 将文件拖到 Claude Desktop 中

选项 2：手动安装

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "MCP Neovim Server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-neovim-server"
      ],
      "env": {
        "ALLOW_SHELL_COMMANDS": "true",
        "NVIM_SOCKET_PATH": "/tmp/nvim"
      }
    }
  }
}

许可证

此 MCP 服务采用 MIT 许可证。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。