This MCP server provides a Python-based interface to manage Xiaozhi agents via the MCP protocol. It exposes tools to modify agent configurations (such as the large language model, TTS model, voice, template, and name) and to retrieve agent lists with flexible queries. When running as an MCP server, clients can call the modify_agent tool to update an agent's attributes and the get_agent_list tool to fetch agent information, supporting queries like total counts, first agent details, and device counts. The server can be used either via the CLI entry point after installation or programmatically as a Python module, enabling both quick ad-hoc operations and deeper integration into other systems. The typical workflow is to start the server with your Xiaozhi API host and token, then issue MCP tool calls to modify or query agents as needed.

Prerequisites:

• Python 3.11 (recommended) and pip
• Basic familiarity with running Python packages

Installation steps:

1. Install from PyPI (recommended): pip install mcp-xiaozhi-server

2. Install from source: git clone https://github.com/yourusername/mcp-xiaozhi-server.git cd mcp-xiaozhi-server pip install -e .

3. Run the server after installation:

   via CLI entry point

   mcp-xiaozhi-server --host https://api.xiaozhi.com --token your_token

   or as a module

   python -m mcp_xiaozhi_server.cli --host https://api.xiaozhi.com --token your_token

4. Optional: set up environment-based configuration export XIAOZHI_API_HOST="https://api.xiaozhi.com" export XIAOZHI_API_TOKEN="your_api_token"

   then in Python:

   from mcp_xiaozhi_server.config import Config config = Config.from_env()

Tips:

• The server supports two configuration modalities: command-line arguments (recommended) and environment variables. If you prefer persistent configuration, set XIAOZHI_API_HOST and XIAOZHI_API_TOKEN in your environment.
• The MCP tools exposed include modify_agent (to change an agent's LLM, TTS, voice, template, or name) and get_agent_list (to fetch agent information with various query options).
• When using the CLI or module, ensure your Xiaozhi API host is reachable and your token has the necessary permissions to modify agents and read agent data.
• If you encounter authentication or network errors, verify that the host URL is correct and that the token is valid for the required endpoints.
• If you want to run the server in a production-like environment, consider wrapping it with a process manager (e.g., systemd) and using environment-based configuration for security and portability.