中文版 | 영어

xiaozhi-mcphub는 Xiaozhi AI 플랫폼에 최적화된 MCP(모델 컨텍스트 프로토콜) 브리지 및 관리 콘솔입니다. 다중 엔드포인트 관리, 자동 재연결, 벡터 기반 스마트 라우팅, OpenAPI 호환 접근을 제공합니다.

🚀 주요 특징

• 향상된 샤오즈 통합:

• 다중 엔드포인트 관리: 여러 Xiaozhi 엔드포인트와의 양방향 WebSocket 연결(활성화/비활성화, 편집, 재연결, 상태 쿼리).

• 스마트 재연결: 빠른 재연결 모드, 지수적 백오프, 무한 재시도와 절전 창 — 모두 환경 변수를 통해 구성할 수 있습니다.

• 도구 동기화: 서버 도구가 변경 시 샤오즈 엔드포인트에 알림을 받아 도구 목록을 최신 상태로 유지합니다.

• 그룹화 및 스마트 라우팅: 엔드포인트는 그룹에 바인딩하거나 $smart 지능형 라우팅을 사용할 수 있습니다.

• MCP 관리 (상속 및 강화됨):

• 표준 MCP 서버(stdio / SSE / HTTP 모드) 관리

• 서버, 도구, 프롬프트를 설명과 그룹화와 함께 활성화/비활성화합니다.

• 통합 MCP 항목, 그룹 항목, 서버 전용 엔드포인트.

• 콘솔 및 인증:

xiaozhi-mcphub: MCP tool bridge and console optimized for the Xiaozhi AI platform

中文版 | English

xiaozhi-mcphub is an MCP (Model Context Protocol) bridge and management console optimized for the Xiaozhi AI platform. It provides multi-endpoint management, automatic reconnection, vector-based smart routing, and OpenAPI-compatible access.

🚀 Key Features

• Enhanced Xiaozhi Integration:

  • Multi-endpoint management: Bidirectional WebSocket connections with multiple Xiaozhi endpoints (enable/disable, edit, reconnect, status query).
  • Smart reconnection: Fast reconnect mode, exponential backoff, infinite retries with sleep window — all configurable via environment variables.
  • Tool synchronization: Xiaozhi endpoints are notified when server tools change to keep tool lists up-to-date.
  • Grouping and smart routing: Endpoints can bind to groups or use $smart intelligent routing.

• MCP Management (inherited and enhanced):

  • Manage standard MCP servers (stdio / SSE / HTTP modes).
  • Enable/disable servers, tools, and prompts with descriptions and grouping.
  • Unified MCP entry, group entry, and server-specific endpoints.

• Console & Authentication:

  • Frontend console (React + Vite + Tailwind) to manage Servers, Groups, Users, Logs, Settings, Xiaozhi Endpoints, and Market.
  • JWT-based authentication with user context middleware and a built-in admin account.

• OpenAPI & Direct Tool Access:

  • Expose OpenAPI documentation and statistics endpoints.
  • Call specific server tools via OpenAPI-compatible endpoints.

🧩 Main Differences from Upstream

• New Xiaozhi endpoint multi-endpoint management and status (backward compatible, focusing on multi-endpoints).
• New per-endpoint reconnection strategies and global fast-reconnect switch.
• Enhanced $smart intelligent routing (optional) with automatic Xiaozhi linkage.
• Database uses PostgreSQL + pgvector, initializing sample servers and admin by default.

🔧 Quick Start

Method 1: Use DockerHub image (recommended)

# Pull the image
docker pull huangjunsen/xiaozhi-mcphub:latest

# Run (adjust DB URL and password to your environment)
# Use DB_URL (1.1.x). Legacy DATABASE_URL from v1.0.3 is still accepted as a fallback.
docker run -d \
  --name xiaozhi-mcphub \
  -p 3000:3000 \
  -e DB_URL="postgres://xiaozhi:[email protected]:5432/xiaozhi_mcphub" \
  -e SMART_ROUTING_ENABLED="false" \
  -v $(pwd)/data:/app/data \
  huangjunsen/xiaozhi-mcphub:latest

# Open the dashboard
# http://localhost:3000

Optional environment variables:

• BASE_PATH: Deploy under a sub-path (e.g., /mcphub).
• JWT_SECRET: JWT secret (recommended to set explicitly in production).
• SMART_ROUTING_ENABLED: Enable/disable smart routing (default “false”).
• OPENAI_API_KEY, OPENAI_API_BASE_URL, OPENAI_API_EMBEDDING_MODEL: Required when enabling smart routing.