xiaozhi-mcp

本地 MCP（Model Context Protocol）框架，用來把自建的工具透過小智AI（xiaozhi.me）的 MCP 接入點，提供給語音智能體使用。

架構

小智AI 雲端 (wss://) ↔ mcp_pipe.py（橋接器）↔ server.py（本地 FastMCP Server，stdio）

安裝

uv sync

設定

1. 登入 xiaozhi.me 控制台，進入智能體的配置角色頁面，取得該智能體專屬的 MCP 接入點網址（wss://...）。
2. 複製 .env.example 為 .env，填入取得的網址：

MCP_ENDPOINT=wss://your-actual-endpoint

3.（若要使用 web_search 工具）到 SerpApi 註冊取得 API Key，填入 .env：

SERPAPI_KEY=your-actual-serpapi-key

執行

uv run mcp_pipe.py server.py

看到 log 出現 Successfully connected to WebSocket server 代表已連上小智AI 的 MCP 接入點。

驗證

橋接器顯示連線成功，不代表工具真的能被呼叫到。請開啟與小智AI 的對話，直接要求它算一個算式，例如「幫我算 8 的平方根」，確認小智AI 回覆的結果是正確的計算結果（8 的平方根約為 2.828），就代表 calculator 工具已經透過橋接器被成功呼叫、算完並回傳。

新增工具

在 server.py 中用 @mcp.tool() 裝飾一個函式即可新增工具，同一個 server 可以有多個工具，mcp_pipe.py 不需要修改。工具名稱與參數命名要清楚（避免縮寫），並用 docstring 說明用途與使用時機，讓大模型知道何時該呼叫它。回傳值建議控制在 1024 bytes 以內。

目前內建的 web_search 工具會呼叫 SerpApi 做 Google 搜尋：優先回傳 Google 的直接解答框內容（answer_box，例如天氣、單位換算、簡單問答）或 knowledge_graph 摘要，都沒有的話才退回最相關那一筆搜尋結果的摘要（避免回傳內容過長）；需要在 .env 設定 SERPAPI_KEY 才能使用，沒設定時會回傳 {"success": false, "error": "SERPAPI_KEY not configured"}。

安全性

server.py 內建的 calculator 工具，是用 eval() 直接執行傳入的 Python 運算式，且沒有做任何沙箱或白名單限制，等同於可以執行任意 Python 程式碼（包含存取檔案系統、匯入任意模組等）。這個工具只是官方範例，目的是快速驗證「小智AI ↔ mcp_pipe.py ↔ server.py」這條連線鏈路是否打通，並不適合留在正式使用的環境中。建議在確認連線成功、換上真正需要的工具後，就把 calculator 移除；在那之前，也不要讓橋接器在無人看管的情況下長時間掛著執行。