MCP-HUB-LITE

License Node.js TypeScript Vitest Fastify Vue.js Claude Code

中文文档

A lightweight MCP management platform designed for independent developers, providing MCP server gateway, grouping, fuzzy search, and MCP HttpStream protocol interface.

Overview

MCP-HUB-LITE is an MCP server gateway designed specifically for independent developers. It acts as a proxy between your frontend and multiple backend MCP servers, providing a unified access interface with support for the MCP JSON-RPC 2.0 protocol.

Core Features

  • MCP Gateway Service: Unified proxy interface for multiple backend MCP servers
  • MCP CLI Tool: Command-line tool for listing and calling MCP tools across servers
  • Server Management: Manage multiple MCP servers through a web interface
  • Tool Search: Search and tool discovery across all servers with aggregation
  • Process Management: Launch and manage MCP server processes via npx/uvx
  • Dual-Mode Session: Stateful (session persistence, SSE, notifications) and stateless (per-request) modes, with UA / header / config priority switching
  • MCP Notification Push: Push notifications/tools/list_changed and notifications/resources/list_changed to connected clients
  • Multi-Instance Support: Run multiple instances of the same MCP server with load balancing
  • Instance Selection Strategies: Support random, round-robin, and unique-by-tag selection
  • Tag System: Organize multiple MCP servers by environment, category, function, etc.
  • Fault Tolerance: System continues to operate when individual servers fail
  • Bilingual Interface: Support for Chinese/English interface switching
  • Configuration Management: Support for hot-reloading and maintenance of .mcp-hub.json
  • MCP Native Resources: Forward resource calls to backend MCP servers
  • Security: Mask sensitive values in config change logs

Quick Start

System Requirements

  • Node.js 22.x or higher
  • npm or yarn
  • Windows, macOS, or Linux

Installation

Install from npm

# Install from npm
npm install -g @loop_ouroboros/mcp-hub-lite

# Start the service
mcp-hub-lite start

# Open UI
mcp-hub-lite ui

Build from source

# Install dependencies
npm install

# Run in development mode (frontend and backend hot reload)
npm run dev

# Build production version
npm run build

# Full check (build + tests + code check)
npm run full:check

# Run production version
npm start

# Check status
mcp-hub-lite status

# Open UI interface
mcp-hub-lite ui

The server will start at http://localhost:7788.

Server Management

Servers

Manage all your MCP servers in one place. Add, edit, delete, connect, and disconnect servers through the intuitive web interface.

Gateway & Tools

Gateway Tools

Aggregated Tools

Discover and call tools from all connected MCP servers through the unified gateway interface. The aggregated tools view provides a single place to search and use all available tools.

Resources

Resources

Browse and manage MCP resources from all connected servers.

Testing

# Run all tests
npm test

# Backend tests
npm run test:backend

# Frontend tests
npm run test:frontend

CLI Commands

MCP-HUB-LITE provides a command-line interface for managing the service.

# Start the service
npm start
# or
mcp-hub-lite start

# Check status
mcp-hub-lite status

# List all servers
mcp-hub-lite list

# Open web interface
mcp-hub-lite ui

# Help
mcp-hub-lite --help

Tool Use Command

The tool-use command provides MCP server tool operations:

# List system tools (default server: mcp-hub-lite)
mcp-hub-lite tool-use list-tools

# List tools from a specific server
mcp-hub-lite tool-use list-tools --server baidu-search

# Get tool schema
mcp-hub-lite tool-use get-tool --tool list_tools

# Call a system tool
mcp-hub-lite tool-use call-tool --tool list_tools --args '{}'

# Call a server tool
mcp-hub-lite tool-use call-tool --server baidu-search --tool search --args '{"query":"hello"}'

Configuration

MCP-HUB-LITE uses a .mcp-hub.json file for configuration. Configuration lookup priority:

  1. Environment variable MCP_HUB_CONFIG_PATH
  2. ~/.mcp-hub-lite/config/.mcp-hub.json (hidden folder in user home directory)

Configuration Example

{
  "version": "1.1.0",
  "servers": [
    {
      "id": "server-1",
      "name": "My MCP Server",
      "description": "Example server",
      "transport": "streamable-http",
      "endpoint": "http://localhost:8080",
      "tags": {
        "env": "development",
        "category": "api-server",
        "function": "http-api",
        "priority": "medium"
      },
      "allowedTools": [],
      "instances": [
        {
          "index": 0,
          "displayName": "Instance 1",
          "enabled": true,
          "env": {}
        }
      ],
      "managedProcess": {
        "command": "npx my-mcp-server",
        "managedMode": "npx",
        "processType": "streamable-http"
      }
    }
  ],
  "settings": {
    "language": {
      "current": "en-US",
      "autoDetect": true,
      "fallback": "en-US"
    },
    "logging": {
      "level": "info"
    }
  },
  "system": {
    "session": {
      "defaultSessionMode": "stateful",
      "sessionModeRules": {
        "stateful": ["Claude"],
        "stateless": ["CherryStudio"]
      }
    }
  },
  "gateway": {
    "proxyTimeout": 30000,
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}

Client Configuration

To connect your MCP client to MCP-HUB-LITE, add the following to your client's MCP configuration:

{
  "mcpServers": {
    "mcp-hub-lite": {
      "type": "http",
      "url": "http://localhost:7788/mcp"
    }
  }
}

Stateful mode provides session persistence, SSE streaming, and real-time notifications. UA matching is NOT automatic — it requires manually adding "ClaudeCode" to system.session.sessionModeRules.stateful in .mcp-hub.json. Standard MCP clients like Claude Code work with the default stateful mode without extra configuration.

{
  "mcpServers": {
    "mcp-hub-lite": {
      "type": "http",
      "url": "http://localhost:7788/mcp",
      "headers": {
        "x-mcp-session-mode": "stateless"
      }
    }
  }
}

CherryStudio requires the x-mcp-session-mode: stateless header to use stateless mode. UA matching is NOT automatic — it requires manually adding "CherryStudio" to system.session.sessionModeRules.stateless in .mcp-hub.json. The header approach is the recommended way and takes highest priority.

Stateless mode uses per-request transport — each POST creates an independent transport, no session persistence, GET returns 405.

Add the x-mcp-session-mode header to force a specific mode:

{
  "mcpServers": {
    "mcp-hub-lite": {
      "type": "http",
      "url": "http://localhost:7788/mcp",
      "headers": {
        "x-mcp-session-mode": "stateful"
      }
    }
  }
}

Valid values: "stateful" or "stateless". Header takes highest priority over UA matching and config defaults.

Usage Guide

Adding MCP Servers

Through the web interface:

  1. Open http://localhost:7788
  2. Navigate to the "Servers" page
  3. Click "Add Server"
  4. Fill in server details and save

Process Management

MCP-HUB-LITE supports launching and managing MCP servers using your local environment:

Supported Launch Methods

  • Node.js (npx): npx package-name
  • Python (uvx): uvx package-name
  • Direct Command: Custom startup command

Process Management Features

  • Start/stop/restart MCP servers
  • Monitor CPU and memory usage
  • Crash detection and automatic restart
  • PID tracking and health checks

Development Guide

Project Structure

src/
├── api/              # API implementations
│   ├── mcp/          # MCP protocol handlers
│   ├── web/          # Web API routes (includes sessions.ts)
│   └── ws/           # WebSocket routes
├── models/           # Data models
├── services/         # Core business logic
│   ├── gateway/      # MCP gateway service
│   ├── connection/   # Connection management
│   └── hub-tools/    # Hub tools service
├── utils/            # Utility functions
│   ├── logger/       # Logging utilities
│   └── transports/   # MCP transport implementations
├── config/           # Configuration
├── cli/              # CLI commands
│   └── commands/     # CLI command implementations
├── pid/              # Process ID management
└── server/           # Server runtime

frontend/
├── src/
│   ├── components/   # Reusable UI components
│   ├── views/        # Page view components
│   ├── stores/       # Pinia state management
│   ├── composables/  # Vue composables
│   ├── router/       # Vue Router configuration
│   ├── i18n/         # Internationalization
│   └── types/        # Frontend type definitions

shared/
├── models/           # Shared models
└── types/           # Shared types

tests/
├── unit/            # Unit tests
├── integration/     # Integration tests
├── contract/        # Contract tests
├── helpers/         # Test helpers
└── types/          # Test types

Adding New Features

  1. Create models (models/)
  2. Implement services (services/)
  3. Add API routes (api/)
  4. Write tests (tests/)
  5. Update configuration files

Detailed Technical Documentation

Complete project architecture, constraints, and design decisions can be found in:

  • CLAUDE.md - Project AI context and module documentation

License

MIT

Contributing

Pull Requests and Issues are welcome!

Community

Thanks to the LinuxDo (linux.do) community for the discussions, sharing, and feedback.