vim-mcp

vim-mcp

用于 Vim 和 Claude Code 的简单 MCP（模型上下文协议）集成。

功能

• 将 Claude Code 连接到某个 Vim 实例
• 查询 Vim 状态（缓冲区、窗口、光标位置等）
• 使用自然语言通过 Claude 执行 Vim 命令

工作原理：

1. MCP 服务在 /tmp/vim-mcp-server.sock 启动 Unix 套接字服务器
2. 每个 Vim 实例作为 Unix 套接字客户端连接到服务器
3. Vim 向服务器发送注册信息和状态更新
4. 服务器维护与所有 Vim 实例的活动连接
5. Claude Code 通过模型上下文协议与 MCP 服务通信

演示

列出并选择 Vim 实例：

终于可以退出 Vim 了！

更多内容请参阅演示 wiki 页面

为什么需要这个？

好吧，我明白它的作用，但我们为什么需要它？

如果你只是想执行基本的 Vim 操作，例如输入“将窗口一分为二”（24 次击键），而不是运行 :sp / :vs（3 次击键），那你最好还是别用它。vim-mcp 的优势在于击键次数未知的情况；也就是你只能描述自己想做什么，却不知道具体该怎么做。复杂的正则表达式、宏、查找、语义搜索帮助等操作，都属于这类情况——告诉 AI 你想完成什么，比反复试错更快。我想我想找的词是迂回表达？

下面是一个可能有用的场景：

假设你想执行一个复杂的 Vim 命令，否则需要花很长时间才能构造出来。只要你能描述想做什么，Claude 就能轻松完成。也许你想把“(test foobar)”替换成方括号，但只有在它出现在三级 Markdown 标题之后时才替换。这种命令我可没法在几秒钟内轻松想出来……但 Claude 可以！

使用 vim-mcp，我可以向 Claude 提示：

In README.md, substitute the set of parentheses `(SOME TEXT)` with square brackets `[SOME TEXT]`, where SOME TEXT says "test foobar"; do this if the strings come after a 3rd-level header markdown.

就这样！我试过之后，Claude 想出了 g 命令并替我执行了。

vim-mcp - vim_execute (MCP)(command: "g/^### /,/^#\\{1,3\\} \\|^$/s/(test foobar)/[test foobar]/g")
  ⎿  Command executed successfully: g/^### /,/^#\{1,3\} \|^$/s/(test foobar)/[test foobar]/g

额外好处：执行过的命令会保存在命令历史中，你可以返回查看并重新执行或修改它们。

如果你后来又想：“嘿，我其实不想把它们替换成方括号 []，而是想换成花括号 {}！”只需打开命令历史（q:、:history，或按 : 后再按上/下方向键），然后进行必要的修改。

于是我按了 :，再按几次上方向键，直到看到 vim-mcp 执行的命令，然后把它改成 :g/^### /,/^#\{1,3\} \|^$/s/(test foobar)/{test foobar}/g。完成！

概述

详细概述请参阅 vim-mcp 概述。

工具和资源

工具：

1. list_vim_instances
2. select_vim_instance
3. get_vim_state
4. vim_execute
5. exit_vim
6. vim_search_help
7. vim_record_macro

资源：

1. vim://instances - 所有可用 Vim 实例的列表
2. vim://state - 所选 Vim 实例的当前状态
3. vim://buffers - 所选 Vim 实例中所有缓冲区的列表
4. vim://tabs - 所选 Vim 实例中所有标签页的列表

安装

前提条件

• Vim 8+，且带有 +channel 功能；或 Neovim 0.5+
• Node.js 18+
• 支持 Unix 域套接字（Linux/macOS）
• 对 /tmp 目录具有文件系统写入权限
• 支持 MCP 的 claude code、claude desktop 或类似工具

安装 Vim 插件

使用 vim-plug：

Plug 'iggredible/vim-mcp'

安装 MCP 服务

MCP 服务是一个 Node 项目。你需要安装依赖项。

选项 1：使用安装脚本

cd ~/.vim/plugged/vim-mcp  # Or wherever your plugin is installed
./install.sh

安装脚本会自动：

• 检查先决条件（Node.js 和 Vim 版本）
• 安装 Node.js 依赖项
• 尝试全局安装 vim-mcp 命令
• 显示正确的 Claude Code 配置

选项 2：手动安装

如果你更喜欢手动安装，或者 install.sh 脚本无法正常运行：

1. 安装 Node.js 依赖项：

cd ~/.vim/plugged/vim-mcp/server
npm install

npm install 还会运行 chmod +x bin/vim-mcp

2.（可选）全局安装，以便在系统范围内使用 vim-mcp 命令（在 /server 目录中）：

npm link

如果由于权限或其他原因而失败，你可以跳过全局安装，并在配置中使用完整路径。

配置 Claude Code

安装后，将以下配置之一添加到 Claude 配置文件中：

如果全局安装成功（可以使用 vim-mcp 命令）：

  "mcpServers": {
    "vim-mcp": {
      "command": "vim-mcp",
      "args": []
    },
  }

如果 npm link 失败：

{
  "mcpServers": {
    "vim-mcp": {
      "command": "node",
      "args": ["/some/path/.vim/plugged/vim-mcp/server/bin/vim-mcp"]
    }
  }
}

卸载

移除 vim-mcp：

1. 从 .vimrc 中移除插件：

" Delete or comment out this line:
" Plug 'iggredible/vim-mcp'

2. 清理插件文件：

:PlugClean

3. 移除全局 vim-mcp 命令（如果已安装）：

npm unlink vim-mcp

4. 从 Claude Code 配置中移除：

编辑 Claude 配置文件，从 mcpServers 中移除 vim-mcp 部分

5. 清理临时文件（可选）：

rm -f /tmp/vim-mcp-server.sock
rm -f /tmp/vim-mcp-registry.json
rm -f /tmp/vim-mcp-preference.txt

6. 重启 Vim 和 Claude Code，确保所有连接都已断开。

快速开始

逐步连接流程

1. 打开 Vim 实例（插件会自动连接）：

vim file1.txt    # First instance
vim file2.txt    # Second instance (in another terminal)

2. 在 Claude Code 中，列出可用的 Vim 实例：

list vim instances

3. 如果找到多个实例，选择一个：

select vim instance file1-vim-12345

可以向客户端提出的提示词

在客户端（claude code）中，你可以：

1. 管理实例：

   • “列出 Vim 实例”
   • “请连接到第一个实例”
   • “选择打开了 README.md 的实例”

2. 控制 Vim：

   • “垂直拆分为两个窗口”
   • “执行 Vim 命令 ”
   • “救命啊，帮我退出 Vim！！！”

3. 搜索 Vim 帮助：

   • “搜索有关使用 channels 的 Vim 帮助”
   • “如何使用 Vim 的 quickfix 列表？”
   • “显示有关 Vim 寄存器的帮助”

4. 录制宏：

   • “录制一个宏，将第一个单词转为大写并向下移动 2 行”
   • “创建一个宏，复制当前行并将其注释掉”
   • “制作一个宏，查找下一个 TODO 并将其标记为 DONE”

5. 查询 Vim：

   • “我有多少个缓冲区？”
   • “打开了哪些缓冲区？”
   • “我的光标位置在哪里？”
   • “显示当前缓冲区的内容”
   • “活动缓冲区有多少行？”
   • “文件是用什么语言编写的？”
   • “打开了哪些窗口？”
   • “BTC 的现实 10 年目标价是多少？”（开玩笑的）

vim-mcp 可以帮你退出 Vim！！

你终于可以退出 Vim 了！尽情欢呼吧！exit_vim 工具提供安全退出功能，包含三种模式：

• 默认（检查）：检查是否有未保存的更改，并在退出前发出警告
• 保存并退出：保存所有已修改的缓冲区并退出（exit vim save_and_exit）
• 强制退出：不保存而直接退出，丢弃更改（exit vim force_exit）

示例：

exit vim                   # Safe exit - warns about unsaved changes
exit vim save_and_exit     # Save all files and exit
exit vim force_exit        # Exit without saving (discard changes)
GET ME OUTTA HERE          # You're free! Successfully exited Vim (there were no unsaved changes).

注意：这是一个玩笑工具，因为很多人 都很难退出 Vim。

Vim 命令

Vim 打开时，插件会自动连接。不过，你也可以在 Vim 中执行以下命令：

• :VimMCPStatus - 检查连接状态
• :VimMCPConnect - 手动连接到服务
• :VimMCPDisconnect - 断开与服务的连接
• :VimMCPReconnect - 重新连接到服务

贡献

我还在摸索如何让它变得更有用。如果你有想法，欢迎提交 PR！