A powerful Neovim plugin for managing MCP (Model Context Protocol) servers
A powerful Neovim plugin that integrates MCP (Model Context Protocol) servers into your workflow. Configure and manage MCP servers through a centralized config file while providing an intuitive UI for browsing, installing and testing tools and resources. Perfect for LLM integration, offering both programmatic API access and interactive testing capabilities through the :MCPHub command.
Thank you to the following people:
:MCPHub)Using lazy.nvim:
{
"ravitemer/mcphub.nvim",
dependencies = {
"nvim-lua/plenary.nvim", -- Required for Job and HTTP requests
},
-- cmd = "MCPHub", -- lazily start the hub when `MCPHub` is called
build = "npm install -g mcp-hub@latest", -- Installs required mcp-hub npm module
config = function()
require("mcphub").setup({
-- Required options
port = 3000, -- Port for MCP Hub server
config = vim.fn.expand("~/mcpservers.json"), -- Absolute path to config file
-- Optional options
on_ready = function(hub)
-- Called when hub is ready
end,
on_error = function(err)
-- Called on errors
end,
log = {
level = vim.log.levels.WARN,
to_file = false,
file_path = nil,
prefix = "MCPHub"
},
})
end
}
Example configuration file:
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"todoist": {
"command": "npx",
"args": ["-y", "@abhiz123/todoist-mcp-server"],
"disabled": true,
"env": {
"TODOIST_API_TOKEN": "your-api-token-here"
}
}
}
}
:MCPHub
You can:
local hub = mcphub.get_hub_instance()
-- Call a tool (sync)
local response, err = hub:call_tool("server-name", "tool-name", {
param1 = "value1"
}, {
return_text = true -- Parse response to LLM-suitable text
})
-- Call a tool (async)
hub:call_tool("server-name", "tool-name", {
param1 = "value1"
}, {
return_text = true,
callback = function(response, err)
-- Use response
end
})
-- Access resource (sync)
local response, err = hub:access_resource("server-name", "resource://uri", {
return_text = true
})
-- Get prompt helpers for system prompts
local prompts = hub:get_prompts()
-- prompts.active_servers: Lists currently active servers
-- prompts.use_mcp_tool: Instructions for tool usage with example
-- prompts.access_mcp_resource: Instructions for resource access with example
MCPHub.nvim provides extensions that integrate with popular Neovim chat plugins. These extensions allow you to use MCP tools and resources directly within your chat interfaces.
Add MCP capabilities to CodeCompanion.
Add it as a dependency to load the plugin before codecompanion:
{
"olimorris/codecompanion.nvim",
dependencies = {
"nvim-lua/plenary.nvim",
"nvim-treesitter/nvim-treesitter",
"ravitemer/mcphub.nvim"
},
},
require("codecompanion").setup({
strategies = {
chat = {
tools = {
["mcp"] = {
-- calling it in a function would prevent mcphub from being loaded before it's needed
callback = function() return require("mcphub.extensions.codecompanion") end,
description = "Call tools and resources from the MCP Servers",
opts = {
requires_approval = true,
}
}
}
}
}
})
See the extensions/ folder for more examples and implementation details.
Add MCP capabilities to Avante.
⚠️ Tool Conflicts: Disable any built-in Avante tools that might conflict with enabled MCP servers to prevent duplicate functionality or unexpected behavior.
Add MCP capabilities to Avante by including the MCP tool in your setup:
require("avante").setup({
-- other config
-- The system_prompt type supports both a string and a function that returns a string. Using a function here allows dynamically updating the prompt with mcphub
system_prompt = function()
local hub = require("mcphub").get_hub_instance()
return hub:get_active_servers_prompt()
end,
-- The custom_tools type supports both a list and a function that returns a list. Using a function here prevents requiring mcphub before it's loaded
custom_tools = function()
return {
require("mcphub.extensions.avante").mcp_tool(),
}
end,
})
Note: You can also access the Express server directly at http://localhost:[port]/api
Environment Requirements
node --version # Should be >= 18.0.0
python --version # Should be installed
uvx --version # Should be installed
npx or uvx - verify these work in your terminalPort Issues
EADDRINUSE error, kill the existing process:
lsof -i :[port] # Find process ID
kill [pid] # Kill the process
Configuration File
mcpServers keyMCP Server Issues
Need Help?
MCPHub.nvim uses an Express server to manage MCP servers and handle client requests:
When setup() is called:
After successful setup:
:MCPHub commandExpress Server Features:
When Neovim instances close:
This architecture ensures:
sequenceDiagram
participant N1 as First Neovim
participant N2 as Other Neovims
participant S as MCP Hub Server
Note over N1,S: First Client Connection
N1->>S: Check if Running
activate S
S-->>N1: Not Running
N1->>S: start_hub()
Note over S: Server Start
S-->>N1: Ready Signal
N1->>S: Register Client
S-->>N1: Registration OK
Note over N2,S: Other Clients
N2->>S: Check if Running
S-->>N2: Running
N2->>S: Register Client
S-->>N2: Registration OK
Note over N1,S: Server stays active
Note over N2,S: Client Disconnection
N2->>S: Unregister Client
S-->>N2: OK
Note over S: Keep Running
Note over N1,S: Last Client Exit
N1->>S: Unregister Client
S-->>N1: OK
Note over S: Grace Period
Note over S: Auto Shutdown
deactivate S
sequenceDiagram
participant N as Neovim
participant P as Plugin
participant S as MCP Hub Server
N->>P: start_hub()
P->>S: Health Check
alt Server Not Running
P->>S: Start Server
S-->>P: Ready Signal
end
P->>S: Register Client
S-->>P: Registration OK
N->>P: :MCPHub
P->>S: Get Status
S-->>P: Server Status
P->>N: Display UI
flowchart LR
A[VimLeavePre] -->|Trigger| B[Stop Hub]
B -->|If Ready| C[Unregister Client]
C -->|Last Client| D[Server Auto-shutdown]
C -->|Other Clients| E[Server Continues]
B --> F[Clear State]
F --> G[Ready = false]
F --> H[Owner = false]
sequenceDiagram
participant C as Chat Plugin
participant H as Hub Instance
participant S as MCP Server
C->>H: call_tool()
H->>H: Check Ready
alt Not Ready
H-->>C: Error: Not Ready
end
H->>S: POST /tools
S-->>H: Tool Result
H-->>C: Return Result
Note over C,S: Similar flow for resources
C->>H: access_resource()
H->>H: Check Ready
H->>S: POST /resources
S-->>H: Resource Data
H-->>C: Return Data
Thanks to: