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-推荐)```bash
brew tap cousine/tap
brew install neovim-mcp
二进制文件将被安装并准备使用。Homebrew自动处理
删除未签名二进制文件的macOS隔离。
#### 选项B:下载预构建二进制文件
从以下网址下载适用于您平台的最新版本
发布页面.
**macOS用户**:下载后,您可能需要删除隔离标志:```bash
xattr -d com.apple.quarantine /path/to/neovim-mcp
或者允许它进入: 系统首选项→ 安全与隐私→ 将军 → Click
“无论如何都要允许”。
备注:此二进制文件未经苹果公司签名或公证。使用起来很安全,但是
为了确保macOS的安全性,需要这一额外步骤。
选项C:从源代码构建```bash
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
#### 验证安装```bash
neovim-mcp --version
您应该看到包括构建详细信息在内的版本信息。
2.使用Socket启动Neovim
在连接AI之前,请在启用RPC的情况下启动Neovim:```bash
nvim --listen /tmp/nvim.sock
**小贴士**:将此添加到您的shell配置文件中,以始终以套接字开头:```bash
alias nvim='nvim --listen /tmp/nvim.sock'
或者将此添加到您的 ~/.config/nvim/init.lua:```lua
vim.fn.serverstart("/tmp/nvim.sock")
### 3.配置您的AI客户端
选择您的AI客户端并按照配置说明进行操作:
#### 克劳德代码
编辑您的Claude Code配置文件:
**macOS/Linux**: `~/.claude/claude_config.json`\
**视窗**: `%USERPROFILE%\.claude\claude_config.json````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````json
{
"mcpServers": {
"neovim": {
"command": "neovim-mcp",
"env": {
"NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
}
}
}
}
重新启动OpenCode以加载新配置。
#### 光标
Cursor通过其设置支持MCP:
1. 打开光标设置(`Cmd+,` 在macOS上, `Ctrl+,` 在Windows/Linux上)
1. 引导到 **特性** → **MCP服务器**
1. 点击 **添加MCP服务器**
1. 配置:
- **名字**: `neovim`
- **命令**: `neovim-mcp` (如果不在path中,则为完整路径)
- **环境变量**:
- 密钥: `NVIM_MCP_LISTEN_ADDRESS`
- 价值: `/tmp/nvim.sock`
1. 保存并重新启动游标
或者,编辑 `~/.cursor/mcp.json` 直接:```json
{
"mcpServers": {
"neovim": {
"command": "neovim-mcp",
"env": {
"NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
}
}
}
}
双子座代码助手
对于Google的Gemini Code Assist(在支持的IDE中):
- 安装Gemini代码辅助插件
- 打开插件设置
- 引导到 MCP配置
- 添加服务器配置:```json
{
"neovim": {
"command": "neovim-mcp",
"env": {
"NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
}
}
}
5. 重新启动IDE
#### Qwen编码器
对于Qwen Coder(如果使用兼容的客户端):
编辑MCP配置文件(位置因客户而异):```json
{
"mcpServers": {
"neovim": {
"command": "neovim-mcp",
"env": {
"NVIM_MCP_LISTEN_ADDRESS": "/tmp/nvim.sock"
}
}
}
}
备注:Qwen Coder的MCP支持可能因客户端实现而异。
查看特定客户的文档以了解确切的配置步骤。
通用MCP客户端
对于任何兼容MCP的客户端:```json
{
"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
1. AI搜索相关功能
1. 阅读代码以了解问题
1. 直接在Neovim缓冲区中进行修复
1. 您查看并保存(或要求更改!)
### “重构此功能”
1. AI读取您当前的函数
1. 提出改进建议
1. 用更好的结构重写它
1. 你可以在Neovim中实时看到这些变化
### “为所有功能添加文档”
1. AI扫描您的文件
1. 查找每个函数定义
1. 添加适当的JSDoc/Godoc注释
1. 您批准并保存
## 配置
### 环境变量
- `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`)
### 自定义套接字路径
如果您喜欢不同的插座位置:```json
{
"mcpServers": {
"neovim": {
"command": "/path/to/neovim-mcp",
"env": {
"NVIM_MCP_LISTEN_ADDRESS": "/home/you/.nvim/mysocket.sock"
}
}
}
}
然后用以下命令启动Neovim:```bash
nvim --listen /home/you/.nvim/mysocket.sock
## 故障排除
### “AI助手看不到我的Neovim实例”
**检查这些东西:**
1. ✅ Neovim是否运行 `--listen /tmp/nvim.sock`?```bash
# Check if socket exists
ls -la /tmp/nvim.sock
- ✅ AI客户端配置中的套接字路径是否相同?
- 检查
NVIM_MCP_LISTEN_ADDRESS在配置文件中
-
✅ 更改配置后是否重新启动了Claude Code?
-
✅ 是通往
neovim-mcp配置中的二进制正确吗?```bash
Test if the binary works
/path/to/neovim-mcp --version
### “权限被拒绝”错误
套接字文件需要读/写权限。检查:```bash
ls -la /tmp/nvim.sock
# Should show: srwx------ (socket with owner permissions)
macOS“损坏且无法打开”或隔离错误
如果您手动下载二进制文件(而不是通过Homebrew),macOS可能会阻止它
因为它没有签名或公证。
快速修复:```bash
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上执行此手动审批步骤。
**自制用户**:安装过程中会自动处理!
### 调试和日志
要启用调试日志记录并将日志保存到文件中,请执行以下操作:```json
{
"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或更高版本
- 尼奥夫:推荐最新稳定版本
- 码头工人:容器化集成测试需要(本地测试可选)
运行测试```bash
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而不是容器
### 代码质量```bash
make lint # Run golangci-lint (strict configuration)
该项目使用基于golden配置的严格golangci-lint配置。看 .golangci.yml 了解详情。
有关详细的开发信息,请参阅 代理商.md.
贡献
我们欢迎捐款!无论您是:
- 🐛 报告错误
- 💡 推荐功能
- 📝 改进文件
- 🔧 提交代码更改
请在GitHub上打开问题或拉取请求。
安装方法总结
方法 · 优点 · 缺点 · 最适合
家酿 · ✅ 自动更新
✅ 无检疫问题
✅ 自动进入PATH · ⚠️ 仅限macOS/Linux · 大多数用户
预构建二进制文件 · ✅ 简单下载
✅ 所有平台|⚠️ 手动更新
⚠️ macOS上的隔离 · Windows,快速测试
从源代码构建 · ✅ 最新代码
✅ 可定制|⚠️ 需要Go工具链
⚠️ 手动构建 · 开发人员、贡献者
从源头构建
如果你想贡献或定制:```bash
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客户端
