Xiaozhi MCP Client: a cross-platform AI assistant supporting voice and text interaction

Xiaozhi Client is a cross-platform AI assistant app developed based on Flutter framework, supporting multiple platforms such as Android, iOS, Web, Windows, macOS and Linux. It realizes real-time voice interaction and text dialog through WebSocket technology, so users can communicate with the AI assistant anytime, anywhere. The project is hosted on GitHub, maintained by developer shenjingnan, and is based on the xiaozhi (xiaozhi-server) ecosystem, which provides flexible service configuration and multi-platform support. The client supports a variety of AI service providers, with voice recognition, text dialog and smart device control, suitable for individual users and developers. The interface is simple and smooth, adapting dark and light color themes to provide users with a convenient interactive experience.

Function List

• Real-time voice interaction: supports users to talk to the AI assistant by voice, with echo cancellation and voice interruption functions.
• Text Dialog: Provides smooth text input and output, suitable for quick queries or complex conversations.
• Multi-platform support: one set of code runs on Android, iOS, Web, Windows, macOS and Linux.
• Service Configuration Management: Supports configuration of multiple Xiaozhi service addresses, WebSocket URLs, Token authentication and custom MAC addresses.
• Dify Service Integration: Supports configuration of multiple Dify services to manage API keys and server URLs.
• Model Selection and Parameter Adjustment: Supports OpenAI interface, Qwen3 model switch thinking mode and temperature and other parameter configurations.
• Dark / light color theme: adapt to different display modes to enhance user experience.
• Enhanced Speech Recognition: Optimize the accuracy of speech recognition and support mixed text and speech conversations.
• OTA auto-enrollment: supports automatic device enrollment to simplify the deployment process.
• Smart device control: integrated MIot function, support to control Mi Home devices.
• Live2D model switching: Built-in free Live2D models, support free import and multi-model switching.
• Innovative Mood Mode: Adjust the interaction according to the user's mood to enhance the personalized experience.

Using Help

Installation process

Xiaozhi client is developed based on Flutter, you need to install Flutter environment to run or build the application. Below are the detailed installation steps:

1. Installing the Flutter Environment
   • Visit the official Flutter website to download and install the Flutter SDK (Windows, macOS, Linux supported).
   • Configure environment variables to ensure that the command line can be runflutterCommand.
   • (of a computer) runflutter doctorCheck that the environment is configured correctly and install missing dependencies (e.g. Android SDK or Xcode).
2. cloning project
   • Open a terminal and run the following command to clone the Xiaozhi client code:

     git clone https://github.com/shenjingnan/xiaozhi-client.git
     

   • Go to the project catalog:

     cd xiaozhi-client
     

3. Installation of dependencies
   • Install the necessary Flutter dependencies by running the following command in the project directory:

     flutter pub get
     

4. Running the application
   • Connect your device (Android/iOS emulator or real phone) and run the following command to launch the app:

     flutter run
     

   • The app will run in debug mode, and the results can be viewed on the device.
5. Building a Release
   • Build APKs for Android devices:

     flutter build apk --release
     

   • Build IPA for iOS devices (needs to run on macOS):

     flutter build ios --release
     

   • Built for the Web platform:

     flutter build web --release
     

   • Note: After the iOS compilation is complete, you need to enable network permissions in the device settings.

Using the main functions

The core function of the Xiaozhi client is voice and text interaction, and the following are the detailed operation instructions:

1. voice interaction
   • Open the app and tap the microphone icon on the main screen to enter voice mode.
   • Speak into the device and the client will recognize the speech and convert it to text in real time.
   • The AI assistant will generate a voice or text response based on the input.
   • If the environment is noisy, enable echo cancellation (turn it on in Settings) to improve recognition accuracy.
   • Support voice interrupt function: you can say "stop" or "re-say" at any time during the conversation to interrupt the current reply and re-enter.
2. text dialog
   • Enter a question or instruction in the input box on the main screen and click the Send button.
   • The AI assistant generates text responses quickly and supports complex question answering or multi-round conversations.
   • Text and voice modes can be mixed, e.g. ask a question with voice and then view the text reply.
3. Service Configuration Management
   • Go to the Settings page and add the Wizards service address (WebSocket URL).
   • Enter a Token for authentication to ensure a secure connection to the server.
   • Multiple Dify services can be configured by entering the API key and server URL and selecting the desired AI model (e.g. OpenAI or Qwen3).
   • Adjust model parameters (e.g., temperature) to control the creativity or accuracy of responses.
4. Intelligent Device Control
   • Enable the MIot function in Settings to connect Mi Home devices (such as smart lights or air conditioners).
   • Use voice commands (e.g. "Turn on the living room light") or text input to control the device.
   • Ensure that the device and the client are in the same network environment.
5. Live2D model switching
   • The app has two free Live2D models built in, and you can switch between them by going to the settings page.
   • Supports importing custom Live2D models: place the model file in the specified directory (refer to the documentation) and select it in the settings.
   • Models are dynamically displayed along with the dialog to enhance the interactive fun.
6. Theme switching
   • Choose a dark or light color theme in the settings to suit different lighting environments.
   • Theme switching takes effect in real time, no need to restart the app.
7. Mood Mode
   • When the mood mode is turned on, the AI will adjust the tone of the reply according to the emotional keywords entered by the user (e.g. "happy" or "tired").
   • For example, if you say "I'm tired today", the AI will reply in a gentler tone, enhancing the user experience.

caveat

• Ensure that the network is stable and that voice interaction requires a real-time connection to the server.
• iOS users will need to grant microphone and network permissions on first run.
• Check the GitHub repository regularly for updates to get the latest features and fixes.
• If you use Dify service, you need to register in Dify platform and get API key in advance.

application scenario

1. Daily Assistant
   Users can check the weather, set reminders or answer questions with the Xiaozhi client. For example, busy office workers can quickly check their schedules or control smart devices at home with voice commands.
2. Learning Assistance
   Students can use the text dialog feature to ask the AI academic questions and get detailed answers. The Graphic Interaction feature, which supports the OpenAI interface, is suitable for analyzing complex documents or images.
3. Smart Home Control
   Users control Mi Home devices through voice or text commands, such as turning on the air conditioner or adjusting the lights, suitable for creating a smart living environment.
4. Developer Debugging
   Developers can utilize the service configuration feature to test different AI models and parameters to quickly verify WebSocket connections or Dify service integration effects.

QA

1. What platforms are supported by the Xiaozhi client?
   It supports Android, iOS, Web, Windows, macOS and Linux, using Flutter development, a set of code adapted to multiple platforms.
2. How to improve speech recognition accuracy?
   Use it in a quiet environment, turn on echo cancellation, and select a high-quality speech recognition model in the settings.
3. Is server support required?
   Yes, you need to connect to xiaozhi-server or Dify service and configure the correct WebSocket URL and API key.
4. How to import a custom Live2D model?
   Place the model file in the application-specified directory (refer to the documentation), and then select the imported model in the settings.
5. What AI models are supported?
   Support OpenAI, Qwen3 and many other models, users can choose and adjust the parameters in the settings.