使用说明

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：

打开光标设置(Cmd+, 在macOS上， Ctrl+, 在Windows/Linux上）
引导到特性 → MCP服务器
点击 添加MCP服务器
配置：
- 名字: neovim
- 命令: neovim-mcp （如果不在path中，则为完整路径）
- 环境变量:
  - 密钥： NVIM_MCP_LISTEN_ADDRESS
  - 价值： /tmp/nvim.sock
保存并重新启动游标

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

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

双子座代码助手

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

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

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

重新启动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”

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

“重构此功能”

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

“为所有功能添加文档”

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

配置

环境变量

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实例”

检查这些东西：

✅ Neovim是否运行 --listen /tmp/nvim.sock?
```
# Check if socket exists
ls -la /tmp/nvim.sock
```
✅ AI客户端配置中的套接字路径是否相同？
- 检查 NVIM_MCP_LISTEN_ADDRESS 在配置文件中
✅ 更改配置后是否重新启动了Claude Code？
✅ 是通往 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编码器: 阿里云

许可证

看许可证了解全部细节。

致谢

内置：

尼奥夫 -可扩展文本编辑器
MCP Go SDK -型号上下文协议实现
go客户端 -Neovim RPC客户端