Neovim MCP

Neov MCP 服务器

使用AI助手控制您的Neovim编辑器！此MCP（模型上下文 Protocol）服务器允许AI代理直接在您的数据库中读取、编辑和导航文件 我的实例

兼容：Claude Code、OpenCode、Cursor、Gemini Code Assist和任何 MCP兼容的AI客户端。

这是什么？

你有没有想过让人工智能助手直接在你的Neovim编辑器中编辑代码？这 服务器使之成为可能！您的AI可以：

• 📝 读取和编辑打开缓冲区中的文件
• 🔍 搜索和导航您的代码
• 🪟 管理窗口和选项卡
• ⚡ 执行Neovim命令
• 🎯 跳到特定的行和位置

在熟悉的Neovim环境中保持完全控制！

支持的AI客户端

此MCP服务器可与支持模型上下文协议的任何客户端配合使用：

• ✅ 克劳德代码 -Anthropic为Claude提供的官方CLI
• ✅ OpenCode -开源AI编码助手
• ✅ 光标 -AI第一代码编辑器
• ✅ 双子座代码助手 -谷歌的AI编码助手
• ✅ Qwen编码器 -阿里巴巴的编码AI（通过MCP兼容客户端）
• ✅ 任何兼容MCP的客户端 -标准MCP协议支持

快速开始

1.安装

选项A：自制（macOS/Linux-推荐）

brew tap cousine/tap
brew install neovim-mcp

二进制文件将被安装并准备使用。Homebrew自动处理 删除未签名二进制文件的macOS隔离。

选项B：下载预构建二进制文件

从以下网址下载适用于您平台的最新版本 发布页面.

macOS用户：下载后，您可能需要删除隔离标志：

xattr -d com.apple.quarantine /path/to/neovim-mcp

或者允许它进入： 系统首选项→ 安全与隐私→ 将军 → Click “无论如何都要允许”。

备注：此二进制文件未经苹果公司签名或公证。使用起来很安全，但是 为了确保macOS的安全性，需要这一额外步骤。

选项C：从源代码构建

# Clone the repository
git clone https://github.com/cousine/neovim-mcp.git
cd neovim-mcp

# Build the server
make build

# The binary will be at dist/neovim-mcp

验证安装

neovim-mcp --version

您应该看到包括构建详细信息在内的版本信息。

2.使用Socket启动Neovim

在连接AI之前，请在启用RPC的情况下启动Neovim：

nvim --listen /tmp/nvim.sock

小贴士：将此添加到您的shell配置文件中，以始终以套接字开头：

alias nvim='nvim --listen /tmp/nvim.sock'

或者将此添加到您的 ~/.config/nvim/init.lua:

vim.fn.serverstart("/tmp/nvim.sock")

3.配置您的AI客户端

选择您的AI客户端并按照配置说明进行操作：

克劳德代码

编辑您的Claude Code配置文件：

macOS/Linux: ~/.claude/claude_config.json\ 视窗: %USERPROFILE%\.claude\claude_config.json

{
  "mcpServers": {
    "neovim": {
      "command": "neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
      }
    }
  }
}

笔记：

• 如果通过Homebrew安装，只需使用 "command": "neovim-mcp" （它在你的路径中）
• 如果手动下载，请使用完整路径： "/full/path/to/neovim-mcp"
• 找到路径： which neovim-mcp

重新启动Claude Code以加载新配置。

OpenCode

编辑您的OpenCode配置文件：

macOS/Linux: ~/.opencode/config.json\ 视窗: %USERPROFILE%\.opencode\config.json

{
  "mcpServers": {
    "neovim": {
      "command": "neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
      }
    }
  }
}

重新启动OpenCode以加载新配置。

光标

Cursor通过其设置支持MCP：

1. 打开光标设置(Cmd+, 在macOS上， Ctrl+, 在Windows/Linux上）
2. 引导到 特性 → MCP服务器
3. 点击 添加MCP服务器
4. 配置：

- 名字: neovim - 命令: neovim-mcp （如果不在path中，则为完整路径） - 环境变量: - 密钥： NVIM_MCP_LISTEN_ADDRESS - 价值： /tmp/nvim.sock

1. 保存并重新启动游标

或者，编辑 ~/.cursor/mcp.json 直接：

{
  "mcpServers": {
    "neovim": {
      "command": "neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
      }
    }
  }
}

双子座代码助手

对于Google的Gemini Code Assist（在支持的IDE中）：

1. 安装Gemini代码辅助插件
2. 打开插件设置
3. 引导到 MCP配置
4. 添加服务器配置：

{
  "neovim": {
    "command": "neovim-mcp",
    "env": {
      "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
    }
  }
}

1. 重新启动IDE

Qwen编码器

对于Qwen Coder（如果使用兼容的客户端）：

编辑MCP配置文件（位置因客户而异）：

{
  "mcpServers": {
    "neovim": {
      "command": "neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
      }
    }
  }
}

备注：Qwen Coder的MCP支持可能因客户端实现而异。 查看特定客户的文档以了解确切的配置步骤。

通用MCP客户端

对于任何兼容MCP的客户端：

{
  "mcpServers": {
    "neovim": {
      "command": "neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
      }
    }
  }
}

4.重新启动AI客户端

重新启动AI客户端（Claude Code、OpenCode、Cursor等）以加载新配置。

5.试试看

与您的AI助手展开对话，并尝试：

“列出我的Neovim实例中打开的所有缓冲区” “在Neovim中打开src/main.go文件” “查找当前缓冲区中出现的所有'TODO'” “在第42行添加注释，解释此函数的作用”

AI能做什么？

📂 文件和缓冲区管理

• 列出所有打开的文件
• 打开、关闭和切换缓冲器
• 查看哪些文件有未保存的更改

✏️ 阅读与编辑

• 读取特定行或整个文件
• 对代码进行精确编辑
• 插入、删除或替换文本
• 保存更改 :w

🔍 搜索和导航

• 搜索文本模式
• 跳转到特定行
• 四处移动光标
• 浏览搜索结果

🪟 窗口控件

• 创建拆分（水平/垂直）
• 调整窗口大小并关闭窗口
• 查看所有打开的窗口

⚡ 高级命令

• 运行任何Vim命令(:w, :q, :s/old/new/g等等）
• 执行Lua代码
• 调用Neovim函数

真实世界的例子

“帮我修复这个bug”

1. 你告诉你的AI你的代码中有一个bug
2. AI搜索相关功能
3. 阅读代码以了解问题
4. 直接在Neovim缓冲区中进行修复
5. 您查看并保存（或要求更改！）

“重构此功能”

1. AI读取您当前的函数
2. 提出改进建议
3. 用更好的结构重写它
4. 你可以在Neovim中实时看到这些变化

“为所有功能添加文档”

1. AI扫描您的文件
2. 查找每个函数定义
3. 添加适当的JSDoc/Godoc注释
4. 您批准并保存

配置

环境变量

• NVIM_MCP_LISTEN_ADDRESS -Neovim套接字的路径（默认： /tmp/nvim.sock)
• NVIM_MCP_SOCKET_ADDRESS -LISTEN_ADDRESS的替代品（用途相同）
• NVIM_MCP_LOG_LEVEL -日志记录级别：调试、信息、警告、错误（默认值： info)
• NVIM_MCP_LOG_FILEPATH -日志文件的路径（默认值：空，日志到stderr）
• NVIM_MCP_LOG_DISABLED -禁用日志记录：true或false（默认值： false)

自定义套接字路径

如果您喜欢不同的插座位置：

{
  "mcpServers": {
    "neovim": {
      "command": "/path/to/neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/home/you/.nvim/mysocket.sock"
      }
    }
  }
}

然后用以下命令启动Neovim：

nvim --listen /home/you/.nvim/mysocket.sock

故障排除

“AI助手看不到我的Neovim实例”

检查这些东西：

1. ✅ Neovim是否运行 --listen /tmp/nvim.sock?

   # Check if socket exists
   ls -la /tmp/nvim.sock

1. ✅ AI客户端配置中的套接字路径是否相同？

- 检查 NVIM_MCP_LISTEN_ADDRESS 在配置文件中

1. ✅ 更改配置后是否重新启动了Claude Code？

1. ✅ 是通往 neovim-mcp 配置中的二进制正确吗？

   # Test if the binary works
   /path/to/neovim-mcp --version

“权限被拒绝”错误

套接字文件需要读/写权限。检查：

ls -la /tmp/nvim.sock
# Should show: srwx------ (socket with owner permissions)

macOS“损坏且无法打开”或隔离错误

如果您手动下载二进制文件（而不是通过Homebrew），macOS可能会阻止它 因为它没有签名或公证。

快速修复：

# Remove the quarantine flag
xattr -d com.apple.quarantine /path/to/neovim-mcp

# Or find where it's installed
xattr -d com.apple.quarantine $(which neovim-mcp)

备选方案： 首选 系统首选项→ 安全与隐私→ 将军 和 点击 “无论如何都允许” 当提示时。

为什么？ 代码签名和公证需要Apple Developer帐户 （99美元/年）。这个项目是开源的，二进制文件可以安全使用，但是 需要在macOS上执行此手动审批步骤。

自制用户：安装过程中会自动处理！

调试和日志

要启用调试日志记录并将日志保存到文件中，请执行以下操作：

{
  "mcpServers": {
    "neovim": {
      "command": "/path/to/neovim-mcp",
      "env": {
        "NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock",
        "NVIM_MCP_LOG_LEVEL": "debug",
        "NVIM_MCP_LOG_FILEPATH": "/tmp/neovim-mcp.log"
      }
    }
  }
}

“未找到缓冲区”

人工智能可能正在寻找一个未打开的缓冲区。确保：

• 该文件实际上已在Neovim中打开
• 您使用的文件名正确（请与 :ls 在Neovim）

提示和最佳实践

以获得最佳效果

• 让 Neovim 可见 -您将实时看到变化！
• 简单开始 -要求AI在编辑之前先读取文件
• 审查变更 -AI会编辑您的实际文件，因此请在之前进行审查

储蓄

• 使用撤消 -如果你不喜欢改变，就点击 u 在Neovim
• 具体说明 -告诉AI确切的文件和要更改的内容

安全提示

• 🔒 这赋予了AI完全的控制权 -它可以读/写任何文件Neovim

可以访问

• 💾 未保存的更改 -除非你要求（或它运行），否则人工智能不会保存

:w)

• 📂 工作目录 -AI在Neovim的当前目录中运行
• 🔐 文件权限 -AI尊重文件权限（无法编辑

只读文件）

性能提示

• 关闭未使用的缓冲区以减少混乱
• 打开文件时使用特定的文件路径
• AI可以比手动滚动更快地搜索！

常见问题解答

Q： AI会看到我的私人文件吗？ A： AI只能看到在Neovim中打开的文件。它无法浏览您的 独立的文件系统。

Q： 我可以撤消AI更改吗？ A： 是的！使用Neovim的正常撤销(u)或撤消树。所有更改都会通过 Neovim的常规编辑系统。

Q： 这适用于Neovim插件吗？ A： 是的！您的所有插件、LSP和配置都正常工作。AI只是 通过其RPC接口控制Neovim。

Q： 我可以在远程Neovim上使用这个吗？ A： 是的，但MCP服务器需要能够访问套接字。SSH端口 转发可以帮助远程实例。

Q： 如果我想阻止AI做出改变怎么办？ A： 只需关闭Neovim或套接字连接。您还可以使用 :set readonly 在特定的缓冲区。

Q： 这在Windows上有效吗？ A： 是的！使用Windows套接字路径，如 \\.\pipe\nvim 并配置 因此。

Q： 为什么macOS的二进制文件没有签名/公证？ A： 代码签名需要一个Apple Developer帐户（99美元/年）。这是一个开放的 源项目和二进制文件可以安全使用。如果通过Homebrew安装 隔离标志会自动删除。有关手动下载，请参阅 上面的故障排除部分。

对于开发者

需求

• 走：1.25.5或更高版本
• 尼奥夫：推荐最新稳定版本
• 码头工人：容器化集成测试需要（本地测试可选）

运行测试

# All tests (unit + integration with containers)
make test

# Unit tests only (fast, no Neovim required)
make test-unit

# Integration tests with Docker containers (default)
make test-integration

# Integration tests with local Neovim
make test-integration-local

# Generate HTML coverage report
make test-coverage

测试环境变量：

• NEOVIM_TEST_VERBOSE=1 -显示详细的测试输出
• NEOVIM_TEST_LOCAL=1 -使用本地Neovim而不是容器

代码质量

make lint                   # Run golangci-lint (strict configuration)

该项目使用基于golden配置的严格golangci-lint配置。看 .golangci.yml 了解详情。

有关详细的开发信息，请参阅 代理商.md.

贡献

我们欢迎捐款！无论您是：

• 🐛 报告错误
• 💡 推荐功能
• 📝 改进文件
• 🔧 提交代码更改

请在GitHub上打开问题或拉取请求。

安装方法总结

✅ 无检疫问题 ✅ 自动进入PATH |⚠️ 仅限macOS/Linux |大多数用户| | 预构建二进制文件 | ✅ 简单下载 ✅ 所有平台|⚠️ 手动更新 ⚠️ macOS上的隔离|Windows，快速测试| | 从源代码构建 | ✅ 最新代码 ✅ 可定制|⚠️ 需要Go工具链 ⚠️ 手动构建|开发人员、贡献者|

从源头构建

如果你想贡献或定制：

# Clone the repo
git clone https://github.com/cousine/neovim-mcp.git
cd neovim-mcp

# Install development dependencies (gotestsum, golangci-lint)
make install-deps

# Run tests
make test

# Build
make build

# The binary is now at dist/neovim-mcp

看 代理商.md 详细的开发指南。

了解更多

关于MCP和Neovim

• 模型上下文协议（MCP）:

模型上下文协议.io

• Neovim RPC文档:

neovim.io/doc/user/api.html

AI客户端

• 克劳德代码: claude.ai/code
• OpenCode: opencode.ai
• 光标: cursor.com
• 双子座代码助手: 谷歌云
• Qwen编码器: 阿里云

许可证

麻省理工学院许可证-版权所有（c）2025 Omar Mekky

看 许可证 了解全部细节。

致谢

内置：

• 尼奥夫 -可扩展文本编辑器
• MCP Go SDK -型号

上下文协议实现

• go客户端 -Neovim RPC客户端

______________________________________________________________________

用AI编码快乐！ 🚀