ravitemer/mcphub.nvim · 上手攻略

• 仓库：ravitemer/mcphub.nvim
• 链接：https://github.com/ravitemer/mcphub.nvim
• 分类：Neovim MCP 客户端插件
• 作者：Tom
• 更新：2026-08-21

这是什么

mcphub.nvim 是 Neovim 的 MCP（Model Context Protocol）客户端插件，将 MCP 服务器集成到 Neovim 编辑工作流中。它通过统一配置管理所有 MCP 服务器，提供图形化界面进行服务器启停、工具测试和资源浏览，并与主流 Neovim AI 聊天插件（Avante.nvim、CodeCompanion.nvim、CopilotChat.nvim）无缝对接。

简单来说：mcphub.nvim 让 Neovim 成为 MCP 服务器的"中央枢纽"，一个配置、多端复用。

解决什么问题

MCP 生态快速发展，主流编辑器（VS Code、Cursor、Claude Desktop、Zed 等）都支持 MCP，但各自的服务器配置互不兼容。开发者通常需要在多个编辑器中重复配置同一套 MCP 服务器，维护成本高。

mcphub.nvim 的解决方案是：在 Neovim 中运行一个统一的 MCP Hub 服务，所有配置的服务器通过单一端点暴露给其他 MCP 客户端。配置一次，即可在 Claude Desktop、Cursor、Cline 等支持 MCP 的编辑器中复用。

快速安装

前置依赖

• Neovim ≥ 0.8.0（含 LuaJIT）
• Node.js ≥ 18.0.0（MCP Hub 服务端需要）
• plenary.nvim（Neovim 插件依赖库）
• mcp-hub（随插件自动安装，或手动构建）
• jq（可选，格式化 servers.json 更美观）

使用 lazy.nvim 安装

-- ~/.config/nvim/lua/plugins/mcphub.lua（或其他插件管理器配置）
{
  'ravitemer/mcphub.nvim',
  dependencies = {
    'nvim-lua/plenary.nvim',
  },
  build = 'bundled_build.lua',  -- 自动打包 mcp-hub 二进制
  config = function()
    require('mcphub').setup({
      use_bundled_binary = true,  -- 使用内置 mcp-hub
    })
  end,
}

⚠️ Neovim 版本注意：部分高级功能（如 Lua Native MCP Servers）可能需要 Neovim 0.10+；基础工具/资源/提示功能在 0.8.0+ 均可使用，建议以官方文档为准。

其他安装方式

NixOS / Home Manager：

inputs.mcphub-nvim.packages."${system}".default

然后在 init.lua 中初始化：

require('mcphub').setup({})

核心用法

配置 MCP 服务器

MCP Hub 配置文件默认位于 ~/.config/mcphub/servers.json，支持 VS Code 格式（.vscode/mcp.json 的配置可直接复用）：

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"],
      "disabled": false
    }
  }
}

配置文件支持 ${env:VAR} 环境变量语法，以及 JSON5 格式（允许注释和尾逗号）。

核心命令

图形界面操作

在 :MCPHub 打开的界面中，可以：

• 添加服务器（a 键）
• 编辑现有配置（e 键）
• 删除服务器（d 键）
• 开关单个工具/资源（t 键切换工具，r 键切换资源）
• 测试工具和资源（直接在界面内执行并查看结果）
• 市场安装（m 键浏览 Marketplace 中的认证服务器）

MCP Hub 工作原理

mcphub.nvim 的架构为 客户端-服务端分离：

1. Lua 插件端：运行在 Neovim 内部，提供 UI 命令和 Lua API
2. mcp-hub 服务端（Node.js）：独立进程，管理所有 MCP 服务器生命周期，提供两个端口： - 管理 API（默认 http://localhost:37373/api）：供插件启停服务器、执行工具、访问资源 - 统一 MCP 端点（http://localhost:37373/mcp）：供其他 MCP 客户端（如 Claude Desktop、Cline）连接，自动命名空间隔离，防止多服务器工具名冲突

统一端点复用示例

在 Claude Desktop 的 mcp.json 中（不用再逐个配服务器）：

{
  "mcpServers": {
    "Hub": {
      "url": "http://localhost:37373/mcp"
    }
  }
}

所有通过 mcphub.nvim 配置的服务器工具，现在 Claude Desktop 也能用。

聊天插件集成

⚠️ 注意：聊天插件集成需要这些插件的特定版本，建议查阅 mcphub.nvim 官方文档 确认版本兼容性。

典型适用场景

1. 多端 MCP 统一管理：在 Neovim 配置一次 MCP 服务器，复用到 VS Code / Cursor / Claude Desktop / Zed 等多个编辑器
2. Neovim AI 编程强化：通过 MCP 服务器为 Neovim 添加文件搜索、Git 操作、数据库访问等工具，喂给 CodeCompanion/Avante 等 AI 编程插件
3. MCP 服务器开发调试：内置工具测试界面，不需要额外启动 Postman 或 curl 命令即可验证 MCP 工具
4. Native Lua MCP 服务器：用 Lua 编写自定义 MCP 服务器，全 Neovim 实例共享，无需重复配置

坑与注意

1. Node.js 必装：mcp-hub 服务端是 Node.js 程序，必须安装 Node.js ≥ 18.0.0，否则插件无法正常启动。
2. 端口 37373 占用：若本机端口 37373 被占用，mcp-hub 启动会失败，需在配置中指定其他端口。
3. 多实例同步：multi-instance 功能可以让所有 Neovim 实例保持配置同步，但需要确保各实例启动顺序和 mcp-hub 服务状态一致。
4. Marketplace 服务器来源：市场中的认证 MCP 服务器由社区提交，安装前建议阅读服务器描述和权限说明。
5. Roots / Sampling 不支持：MCP 规范的这两个部分目前尚未支持，若有相关需求暂无法满足。
6. systemd 延迟停止：可配置 shutdown-delay，在 mcp-hub 作为 systemd 服务时延迟停止，避免正在处理的请求被强制中断。

与同类对比

一句话结论：mcphub.nvim 是 Neovim 生态中最完整的 MCP 客户端方案，如果你已经在用 Avante.nvim 或 CodeCompanion.nvim 等 AI 聊天插件，mcphub.nvim 是将 MCP 工具引入 Neovim 工作流的最佳入口；即使不用聊天插件，它的多端复用架构本身也极具价值。

相关资源

• 官方文档：https://ravitemer.github.io/mcphub.nvim/
• GitHub：https://github.com/ravitemer/mcphub.nvim
• Discord 社区：https://discord.gg/NTqfxXsNuN
• MCP Server Finder：https://www.mcpserverfinder.com/servers/ravitemer/mcphub.nvim
• mcp-hub 服务端：https://github.com/ravitemer/mcp-hub