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 testing tools and resources. Perfect for LLM integration, offering both programmatic API access and interactive testing capabilities through the :MCPHub command.

• Simple single-command interface (:MCPHub)
• Interactive UI for testing tools and resources
• Automatic server lifecycle management across multiple Neovim instances
• Smart shutdown handling with configurable delay
• Both sync and async operations supported
• Clean client registration/cleanup
• Comprehensive API for tool and resource access

Using lazy.nvim:

{
    "ravitemer/mcphub.nvim",
    dependencies = {
        "nvim-lua/plenary.nvim",  -- Required for Job and HTTP requests
    },
    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,
            shutdown_delay = 0, -- Wait 0ms before shutting down server after last client exits
            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"
      }
    }
  }
}

• Neovim >= 0.8.0
• Node.js >= 18.0.0
• plenary.nvim
• mcp-hub (automatically installed via build command)

1. Open the MCPHub UI to test tools and monitor server status:

:MCPHub

2. Use the hub instance in your code:

-- Get hub instance after setup
local mcphub = require("mcphub")

-- Option 1: Use on_ready callback
mcphub.setup({
    port = 3000,
    config = vim.fn.expand("~/mcpservers.json"),
    on_ready = function(hub)
        -- Hub is ready to use here
    end
})

-- Option 2: Get hub instance directly (might be nil if setup in progress)
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({
    use_mcp_tool_example = [[<use_mcp_tool>
<server_name>weather-server</server_name>
<tool_name>get_forecast</tool_name>
<arguments>
{
  "city": "San Francisco",
  "days": 5
}
</arguments>
</use_mcp_tool>]],
    access_mcp_resource_example = [[<access_mcp_resource>
<server_name>weather-server</server_name>
<uri>weather://san-francisco/current</uri>
</access_mcp_resource>]]
})
-- 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.

• CodeCompanion Integration: 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 = {
            agents = {
                tools = {
                    ["mcp"] = {
                        callback = require("mcphub.extensions.codecompanion"),
                        description = "Call tools and resources from the MCP Servers",
                        opts = {
                            user_approval = true
                        }
                    }
                }
            }
        }
    }
  })

See the extensions/ folder for more examples and implementation details.

Note: You can also access the Express server directly at http://localhost:[port]/api

1. Environment Requirements

   • Ensure these are installed as they're required by most MCP servers:

     node --version    # Should be >= 18.0.0
     python --version  # Should be installed
     uvx --version    # Should be installed

   • Most server commands use npx or uvx - verify these work in your terminal

2. Port Issues

   • If you get EADDRINUSE error, kill the existing process:

     lsof -i :[port]  # Find process ID
     kill [pid]       # Kill the process

3. Configuration File

   • Ensure config path is absolute
   • Verify file contains valid JSON with mcpServers key
   • Check server-specific configuration requirements
   • Validate server command and args are correct for your system

4. MCP Server Issues

   • Validate server configurations using either:
     • MCP Inspector: GUI tool for verifying server operation
     • mcp-cli: Command-line tool for testing servers with config files
   • Check server logs in MCPHub UI (Logs view)
   • Test tools and resources individually to isolate issues

5. Need Help?

   • Create a Discussion for questions
   • Open an Issue for bugs

MCPHub.nvim uses an Express server to manage MCP servers and handle client requests:

1. When setup() is called:

   • Checks for mcp-hub command installation
   • Verifies version compatibility
   • Starts mcp-hub with provided port and config file
   • Creates Express server at localhost:[port]

2. After successful setup:

   • Calls on_ready callback with hub instance
   • Hub instance provides REST API interface
   • UI updates in real-time via :MCPHub command

3. Express Server Features:

   • Manages MCP server configurations
   • Handles tool execution requests
   • Provides resource access
   • Multi-client support
   • Automatic cleanup

4. When Neovim instances close:

   • Unregister as clients
   • Last client triggers shutdown timer
   • Server waits shutdown_delay seconds before stopping
   • Timer cancels if new client connects

This architecture ensures:

• Consistent server management
• Real-time status monitoring
• Efficient resource usage
• Clean process handling
• Multiple client support

Currently working on the following features:

• Enable/disable MCP servers directly from the hub UI
• Enable/disable specific tools within a server
• Add custom descriptions for each MCP server through the UI
• Configure server settings via server interface or config file

Thanks to:

• nui.nvim for inspiring our text highlighting utilities