# MCP-HUB-LITE [![License](https://img.shields.io/badge/license-MIT-080f12?style=flat&colorA=080f12&colorB=1fa669)](./LICENSE) [![Node.js](https://img.shields.io/badge/Node.js-22.x-080f12?style=flat&logo=nodedotjs&logoColor=white&colorA=080f12&colorB=339933)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-080f12?style=flat&logo=typescript&logoColor=white&colorA=080f12&colorB=3178C6)](https://www.typescriptlang.org/) [![Vitest](https://img.shields.io/badge/Vitest-Testing-080f12?style=flat&logo=vitest&logoColor=white&colorA=080f12&colorB=6E9F18)](https://vitest.dev/) [![Fastify](https://img.shields.io/badge/Fastify-Web-080f12?style=flat&logo=fastify&logoColor=white&colorA=080f12&colorB=000000)](https://fastify.io/) [![Vue.js](https://img.shields.io/badge/Vue.js-3-080f12?style=flat&logo=vuedotjs&logoColor=white&colorA=080f12&colorB=4FC08D)](https://vuejs.org/) [![Claude Code](https://img.shields.io/badge/Claude-Code-1fa669?style=flat&colorA=080f12&colorB=1fa669)](https://claude.ai/code) --- [中文文档](./README_zh.md) 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 ```bash # 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 ```bash # 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 . ## Server Management ![Servers](./docs/screenshot/en/servers.png) Manage all your MCP servers in one place. Add, edit, delete, connect, and disconnect servers through the intuitive web interface. ## Gateway & Tools ![Gateway Tools](./docs/screenshot/en/gateway-tools.png) ![Aggregated Tools](./docs/screenshot/en/aggregated-tool.png) 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](./docs/screenshot/en/resources.png) Browse and manage MCP resources from all connected servers. ### Testing ```bash # 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. ```bash # 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: ```bash # 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
Click to expand full .mcp-hub.json example ```json { "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:
Claude Code / Claude Desktop (stateful mode — default) ```json { "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.
CherryStudio (stateless mode) ```json { "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.
Manual session mode override Add the `x-mcp-session-mode` header to force a specific mode: ```json { "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 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](./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.