Tdengine MCP

🚀 TDengine 查詢 MCP 服務器

一個提供只讀 TDengine 數據庫查詢的模型上下文協議 (MCP) 服務器，專為 AI 助手打造。藉助該服務器，您能執行查詢、探索數據庫結構，並直接通過 AI 工具調查數據。

🚀 快速開始

此 MCP 服務器可與任何支持 Model Context Protocol 的工具協同使用，以下為您介紹支持的 AI 工具及使用方法。

支持的 AI 工具

• Cursor IDE：在 .cursor/mcp.json 中進行設置。
• Anthropic Claude：搭配兼容的 MCP 客戶端使用。
• 其他支持 MCP 的 AI 助手：按照工具的 MCP 配置說明操作即可。

✨ 主要特性

功能

• ✅ 執行 只讀 TDengine 查詢（僅支持 SELECT、SHOW、DESCRIBE）。
• ✅ 提供數據庫/穩定信息和元數據。
• ✅ 列出可用數據庫和穩定表。

不支持的功能

• ❌ 執行寫入操作（如 INSERT、UPDATE、DELETE、CREATE、ALTER 等）。
• ❌ 提供數據庫設計或架構生成功能。
• ❌ 作為完整的數據庫管理工具。

此工具專為 數據調查和探索 設計，僅支持只讀查詢，不用於數據庫管理、模式管理或數據修改。

📦 安裝指南

從源代碼運行

推薦使用 此方法，可直接從源代碼使用 uv 運行，無需安裝。Claude Desktop 和 Cursor 示例中的配置即採用此方式。 若要克隆倉庫，可執行以下命令：

git clone https://github.com/Abeautifulsnow/tdengine-mcp.git
cd tdengine-mcp

之後，您可以直接運行服務器：

uv run src/tdengine_mcp_server -th 192.100.8.22 -db log -ll debug

或者，您也可以修改 src/tdengine_mcp_server/ 目錄中的 .env 文件來設置環境變量，然後使用以下命令運行服務器：

uv run src/tdengine_mcp_server

⚠️ 重要提示

默認情況下，數據庫名稱為 default。

通過 pip 安裝

您也可以使用 Python 包進行安裝：

pip install tdengine-mcp-server

安裝完成後，啟動服務器：

tdengine-mcp-server --config your_config_file.yaml

💻 使用示例

示例查詢

你能使用查詢工具顯示數據庫中的前 10 條記錄嗎？

我需要分析我們的銷售數據。能否運行一個 SQL 查詢以獲取上個月按區域劃分的總銷售額，從開發數據庫中？

你能列出我們所有的可用數據庫嗎？

使用 TDengine 查詢 MCP 工具

TDengine Query MCP 服務器提供了三個主要工具，您的 AI 助手可以使用：

基礎用法

對特定穩定表執行只讀 SQL 查詢：

使用查詢工具運行以下命令：

SELECT * FROM customers WHERE itemid > '2025-01-01' LIMIT 10;

高級用法

獲取指定穩定表的詳細信息：

使用 info 工具檢查指定穩定的元數據。

DESCRIBE disks_info;

📚 詳細文檔

安全注意事項

• ✅ 只允許只讀查詢（SELECT、SHOW、DESCRIBE）

故障排除

連接問題

若遇到連接問題，可按以下步驟排查：

1. 驗證您的數據庫憑證是否已正確配置在 MCP 配置中。
2. 確保 TDengine 服務器正在運行且可正常訪問。
3. 檢查防火牆規則是否阻止了連接。
4. 啟用調試模式，在您的配置中設置 LOG_LEVEL。

常見錯誤

錯誤：查詢執行失敗

• 驗證您的 SQL 語法。
• 確保僅使用支持的查詢類型（SELECT、SHOW、DESCRIBE）。
• 確保您的查詢確實是只讀的。

🤝 貢獻

歡迎貢獻！請隨意提交 Pull Request。

如需更多信息或支持，請在 GitHub 倉庫 上打開問題。