🚀 NexusHub

Unified MCP Server for Claude AI Tools

<p align="center">

</p>

<p>
<strong>A powerful bridge between Claude AI and external services via Model Context Protocol.</strong><br>
Enhance Claude Code with filesystem access, database operations, vector search, GitHub integration, and more.
</p>

Demo •
Documentation •
Report Bug •
Request Feature

</div>

---

✨ Features

- 📡 Dual Interface - Supports both HTTP and stdio MCP protocols
- 💅 Modern Dashboard - Beautiful Protocol design system admin interface with dark mode by default
- 🔌 Integrated Services - Combines multiple MCP servers (Memory, GitHub, Brave Search)
- 🔍 Vector Database - Document ingestion and semantic search capabilities
- 🔑 API Management - Securely manage API keys and service configurations
- 🐳 Docker Integration - Easy deployment with Docker and Docker Compose
- 📋 Advanced Prompts - Pre-configured prompts for effective AI interactions
- 🔄 Real-time Status - Monitor the health of all connected services

<div align="center">
<br>

<br>
<em>The elegant NexusHub dashboard interface with Protocol design system</em>
<br>
</div>

🏛️ Architecture

NexusHub uses a Node.js backend with Express for the HTTP interface and native stdio handling for the CLI interface. The server integrates with several key services:

┌─────────────────────────────────────────────────────┐
│                  Claude Desktop                     │
└───────────┬─────────────────┬───────────┬───────────┘
            │                 │           │
            ▼                 ▼           ▼           
┌───────────────────┐ ┌─────────────┐ ┌─────────────┐ 
│    NexusHub MCP   │ │ Memory MCP  │ │ GitHub MCP  │ 
│       Server      │ │   Server    │ │   Server    │ 
└─────────┬─────────┘ └─────────────┘ └─────────────┘ 
          │                  ▲                ▲        
          ▼                  │                │        
┌─────────────────┐          │                │        
│  Vector Store   │          │                │        
└─────────────────┘          │                │        
          │                  │                │        
          ▼                  │                │        
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│ Filesystem API  │ │ Database API│ │   Docker API    │
└─────────────────┘ └─────────────┘ └─────────────────┘

🛠️ Available Tools

NexusHub provides the following tools to Claude AI:

| Category | Tool | Description |
|----------|------|-------------|
| Filesystem | fs_list_files | List files in a directory |
| | fs_read_file | Read file contents |
| | fs_write_file | Write to a file |
| Database | db_execute_query | Execute a read-only SQL query |
| | db_list_tables | List all tables in the database |
| | db_describe_table | Get table schema |
| | db_insert_data | Insert data into a table |
| Docker | docker_list_containers | List Docker containers |
| | docker_start_container | Start a container |
| | docker_stop_container | Stop a container |
| | docker_get_container_logs | Get container logs |
| Search | serper_search | Perform web search via Serper API |
| Vector DB | ingest_docs | Ingest documents into the vector store |
| | vector_search | Search for similar documents |

🚀 Getting Started

Prerequisites

- Docker and Docker Compose
- Node.js 18+
- Python 3.8+ (for vector embedding)

Installation

1. Clone the repository:

   git clone https://github.com/webdevtodayjason/NexusHub.git

   cd NexusHub

   

2. Set up environment variables:

   cp .env.example .env

   # Edit .env file with your API keys

   

3. Start the services:

   docker-compose up -d

   

4. Access the dashboard:
Open http://localhost:8001/dashboard in your browser

Configuration for Claude Desktop

NexusHub supports two different integration methods with Claude Desktop:

1. HTTP Mode

This mode connects to NexusHub via HTTP endpoints. Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nexushub": {
      "name": "NexusHub MCP Server",
      "description": "Centralized MCP server with multiple capabilities",
      "url": "http://localhost:8001/mcp",
      "enabled": true
    }
  }
}

2. STDIO Mode (Recommended)

This mode uses direct process communication for better performance and reliability. It requires the NexusHub code to be available locally:

1. Prepare the wrapper scripts:

   # Make the wrapper script executable

   chmod +x /path/to/nexushub/nexushub-mcp.sh

   chmod +x /path/to/nexushub/src/mcp/adapters/stdio-wrapper.js

   chmod +x /path/to/nexushub/src/mcp/stdio-adapter.js

   

2. Add to your claude_desktop_config.json:

   {

     "mcpServers": {

       "nexushub": {

         "name": "NexusHub MCP Server",

         "description": "Centralized MCP server with multiple capabilities",

         "command": "/path/to/nexushub/nexushub-mcp.sh",

         "enabled": true

       },

       "brave-search": {

         "name": "Brave Search MCP",

         "description": "Provides web search capabilities via Brave Search API.",

         "command": "docker",

         "args": ["exec", "-i", "mcp_brave_search", "node", "dist/index.js"],

         "enabled": true

       },

       "github": {

         "name": "GitHub MCP",

         "description": "Provides GitHub repository interaction.",

         "command": "docker",

         "args": ["exec", "-i", "mcp_github", "node", "dist/index.js"],

         "enabled": true

       },

       "memory": {

         "name": "Memory MCP",

         "description": "Persistent knowledge graph memory.",

         "command": "docker",

         "args": ["exec", "-i", "mcp_memory", "node", "dist/index.js"],

         "enabled": true

       }

     }

   }

   

Note: Replace /path/to/nexushub with your actual NexusHub installation path.

Docker Containers

Make sure all Docker containers are running before starting Claude Desktop:

cd /path/to/nexushub
docker-compose up -d

This will start all required MCP servers:
- NexusHub (primary server with filesystem, database, Docker tools)
- Brave Search MCP (web search capabilities)
- GitHub MCP (repository interaction)
- Memory MCP (knowledge graph/persistent memory)

💡 Example Usage

Here are some examples of how to use NexusHub with Claude AI:

File Operations

Please use fs_list_files to show me all the JavaScript files in the src directory, 
then read the content of any interesting files you find.

Database Query

Can you use db_execute_query to find all users in the database who joined 
in the last month and have the "admin" role?

Vector Search

Please use vector_search to find documentation related to "authentication flow" 
and summarize the key points.

Combined Tools

First, use brave_web_search to find the latest best practices for React error boundaries. 
Then, use fs_read_file to examine our current implementation in ErrorBoundary.jsx, 
and suggest improvements based on what you found.

🧩 How to Add Your Own Tools

You can extend NexusHub with custom tools by adding new tool definitions to the /src/mcp/tools/ directory:

// src/mcp/tools/my-custom-tools.js
export function getToolDefinitions() {

  return {

    my_custom_tool: {

      name: 'my_custom_tool',

      description: 'Description of what the tool does.',

      inputSchema: {

        type: 'object',

        properties: {

          param1: {

            type: 'string',

            description: 'Description of parameter 1'

          }

          // Add more parameters as needed

        },

        required: ['param1']

      }

    }

  };

}
// Tool implementation

export async function myCustomTool(param1) {

  // Your custom tool logic here

  return { result: 'Success!' };

}

Then add the tool to /src/mcp/tools/index.js and /src/mcp/tools/handler.js.

🔄 Local Development

1. Install dependencies:

   npm install

   

2. Run in development mode:

   npm run dev

   

3. For stdio mode testing:

   npm run stdio

   

🧪 Running Tests

```bash