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 仓库 上打开问题。