NestJS Xiaozhi MCP Server

A high-performance Model Context Protocol (MCP) Hub & Gateway built with NestJS (v12) for the Xiaozhi ESP32 AI assistant ecosystem.

🌟 Overview

NestJS Xiaozhi MCP Server acts as a unified central bridge between the Xiaozhi AI voice assistant (ESP32) and external capabilities. It aggregates:

1. 7 Local Business Tools: Daily schedule, alarm/reminders, real-time stock quotes (FTS, SSI, VND, AAPL, TSLA), and task/todo management.

2. 37 Dynamic OmniRoute Agentic Tools: Persistent Long-Term Memory, AgentSkills, OmniSkills sandbox execution, webhooks, and advanced automations retrieved dynamically via SSE from OmniRoute (https://ai.tuanphongoto.com/api/mcp/sse).

3. Dual Protocol Transports: Full support for standard MCP SSE Transport (recommended for Xiaozhi) and legacy single-turn HTTP JSON-RPC.

4. Production-Ready Docker Setup: Multi-stage build on Alpine, non-root execution, strictly bounded resource consumption (512MB RAM / 1.0 CPU), V8 GC tuning, log rotation, and native healthchecks.

Related MCP server: iot-mcp-bridge

🏗️ System Architecture

graph TD
    subgraph Edge Layer [Hardware & Voice]
        ESP32[📻 ESP32 XiaoZhi Robot / Speaker]
    end

    subgraph Core AI Server [XiaoZhi Core]
        XiaozhiBackend[🖥️ XiaoZhi Backend Server<br/>STT / TTS / WebSocket Protocol]
        LLM[🤖 LLM via OmniProxy / OpenAI]
    end

    subgraph MCP Hub [NestJS Xiaozhi MCP Server - Port 3000]
        HealthCtrl[💓 /health Monitoring]
        McpCtrl[🔌 McpController<br/>GET /mcp/sse & POST /mcp/messages]
        McpEngine[⚙️ McpServer Engine<br/>Factory Pattern Sessions]
        Business[💼 Business Services<br/>Schedule / Finance / Todo]
        OmniBridge[⚡ OmniRouteClientService<br/>Auto-reconnect & Sync]
    end

    subgraph Remote Cloud [AI Gateway]
        OmniRoute[🌐 OmniRoute MCP Server<br/>37 Agentic Tools / Memory / Skills]
    end

    ESP32 <-->|Opus Frames / WebSocket| XiaozhiBackend
    XiaozhiBackend <-->|Prompt & Tools List| LLM
    XiaozhiBackend <-->|MCP SSE Transport| McpCtrl
    McpCtrl --> McpEngine
    McpEngine --> Business
    McpEngine <-->|Dynamic Remote Tools| OmniBridge
    OmniBridge <-->|SSE Client Transport| OmniRoute

🛠️ Tech Stack

• Framework: NestJS (v12)

• Protocol: Model Context Protocol via @modelcontextprotocol/sdk (v1.30+)

• Runtime: Node.js 22 LTS (ESM syntax)

• Package Manager: pnpm

• Language: TypeScript (Strict Mode)

• Testing: Vitest

• Linting: Oxlint & Prettier

• Containerization: Docker & Docker Compose (Multi-stage Alpine, non-root user node)

🧰 Available MCP Tools (Total: 44 Tools)

1. Local Business Tools (7 Tools)

2. OmniRoute Agentic Tools (37 Dynamic Tools)

When OMNIROUTE_ENABLED=true, the server connects to OmniRoute and dynamically surfaces 37 agentic tools across 13 scopes, including:

• Persistent Agent Memory: memory_set, memory_get, memory_search (Allows XiaoZhi to remember user preferences across sessions).

• AgentSkills & OmniSkills: Dynamic skill registry and sandbox execution.

• Chaos Mode & A2A: Multi-model parallel execution and agent-to-agent protocol triggers.

• System Webhooks & Utilities: Remote execution and automation integrations.

📡 Protocol & Endpoints

⚙️ Environment Variables

Create a .env file in the root directory (see .env.example):

🚀 Deployment & Running

Option 1: Production Deployment with Docker Compose (docker-compose.prod.yml)

The production Compose configuration (docker-compose.prod.yml) pulls the pre-built, multi-architecture image directly from GitHub Container Registry (GHCR). On production servers, no source code or build dependencies are needed—only .env and docker-compose.prod.yml:

# 1. Pull the latest production image
docker compose -f docker-compose.prod.yml pull

# 2. Start container in detached mode
docker compose -f docker-compose.prod.yml up -d

# 3. Check health and real-time logs
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f

# 4. Graceful stop
docker compose -f docker-compose.prod.yml down

Option 2: Run Directly with Docker CLI

# Pull and run directly from GHCR
docker pull ghcr.io/shirotamada/nestjs-xiaozhi-mcp-server:latest

docker run -d \
  --name nestjs-xiaozhi-mcp-prod \
  -p 3000:3000 \
  --env-file .env \
  --restart always \
  ghcr.io/shirotamada/nestjs-xiaozhi-mcp-server:latest

Option 3: Local Build & Development with Docker Compose (docker-compose.yml)

The included Dockerfile and docker-compose.yml feature:

• Strict Resource Boundaries: Maximum 512MB RAM and 1.0 CPU core limit to safeguard host resources.

• Node.js Memory Tuning: NODE_OPTIONS="--max-old-space-size=384" triggers V8 Garbage Collection proactively before hitting the 512MB container ceiling.

• Security: Runs under unprivileged user node (non-root).

• Log Rotation: Capped at 3 files $\times$ 20MB to prevent disk exhaustion.

• Automated Healthcheck: Pings GET /health every 30s.

# 1. Pull & run (or build locally if needed)
docker compose up -d

# 2. Inspect container status and health
docker compose ps

# 3. View real-time logs
docker compose logs -f

# 4. Check health endpoint
curl http://localhost:3000/health

# 5. Stop container
docker compose down

Option 4: Local Development (Without Docker)

# Install dependencies
pnpm install

# Run in watch mode (development)
pnpm run start:dev

# Run in production mode
pnpm run build
pnpm run start:prod

📻 Integration with XiaoZhi ESP32 Server

1. Open your XiaoZhi backend server configuration (config.yaml or data/.config.yaml).

2. Add nestjs-xiaozhi-hub under mcp.global.servers:

mcp:
  global:
    enabled: true
    servers:
      - name: "nestjs-xiaozhi-hub"
        sse_url: "http://<SERVER_IP>:3000/mcp/sse"
        enabled: true
        reconnect_interval: 5
        max_reconnect_attempts: 10
        # headers:
        #   Authorization: "Bearer your-secret-api-key" # Uncomment if MCP_API_KEY is configured

A ready-to-use template is available at templates/xiaozhi-config.yaml.

3. Restart the XiaoZhi server. XiaoZhi will discover all 44 tools automatically!

🧪 Testing & Code Quality

# Run unit tests
pnpm run test

# Run tests with coverage
pnpm run test:cov

# Run fast code linter (Oxlint)
pnpm run lint

# Format codebase (Prettier)
pnpm run format

📄 License

UNLICENSED