xiaozhi-mcp
A local MCP server framework for connecting custom tools to the xiaozhi AI voice agent, with built-in calculator and web search (via SerpApi) tools.
README
xiaozhi-mcp
本地 MCP（Model Context Protocol）框架，用來把自建的工具透過小智AI（xiaozhi.me）的 MCP 接入點，提供給語音智能體使用。
架構
小智AI 雲端 (wss://) ↔ mcp_pipe.py（橋接器）↔ server.py（本地 FastMCP Server，stdio）
安裝
uv sync
設定
- 登入 xiaozhi.me 控制台，進入智能體的配置角色頁面，取得該智能體專屬的 MCP 接入點網址（
wss://...）。 - 複製
.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 移除；在那之前，也不要讓橋接器在無人看管的情況下長時間掛著執行。
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.