TDengine 查询 MCP 服务器

这是一个提供只读 TDengine 数据库查询的 Model Context Protocol (MCP) 服务器，适用于 AI 助手。执行查询、探索数据库结构，并通过您的 AI 工具直接调查数据。

支持的 AI 工具

此 MCP 服务器与支持 Model Context Protocol 的任何工具兼容，包括：

• Cursor IDE：在 .cursor/mcp.json 中设置
• Anthropic Claude：使用兼容的 MCP 客户端
• 其他兼容 MCP 的 AI 助手：遵循工具的 MCP 配置说明

特点与限制

它能做什么

• ✅ 执行只读 TDengine 查询（仅限 SELECT, SHOW, DESCRIBE）
• ✅ 提供数据库/稳定信息及元数据
• ✅ 列出可用的数据库和稳定

它不能做什么

• ❌ 执行写操作（INSERT, UPDATE, DELETE, CREATE, ALTER 等）
• ❌ 提供数据库设计或模式生成功能
• ❌ 作为完整的数据库管理工具

此工具专门用于通过只读查询进行数据调查和探索。不适用于数据库管理、模式管理和数据修改。

如何使用

从源代码运行

推荐的方式是直接使用 uv 运行此 MCP 服务器，无需安装。Claude Desktop 和 Cursor 在下面的例子中都是这样配置的。

如果您想克隆仓库：

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

然后可以直接运行服务器：

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

重要：.env 文件中的设置优先级高于命令行参数。

使用 pip 命令从 PyPI 安装

# 全局安装
pip install tdengine_mcp_server

然后运行：

python -m tdengine_mcp_server -h

使用 uvx 命令安装

uvx tdengine-mcp-server -h

使用 npx 命令从 smithery 安装

npx -y @smithery/cli@latest install @Abeautifulsnow/tdengine-mcp --client cursor --config '"{}"'

您可以在 --client 选项后更改客户端，例如 claude, 'windsurf' 等。也可以参考这个：smithery/tdengine-mcp-server

配置选项

.env 文件

环境变量	描述	默认值
LOG_LEVEL	设置日志级别（DEBUG, INFO, WARN, ERROR）	INFO
TDENGINE_HOST	数据库主机地址	localhost
TDENGINE_PORT	数据库端口	6041
TDENGINE_USERNAME	数据库用户名	root
TDENGINE_PASSWORD	数据库密码	taosdata
TDENGINE_DATABASE	数据库名称	log
TDENGINE_TIMEOUT	设置连接超时时间（秒）	30
TRANSPORT	控制使用的传输方式	stdio

命令行使用

$ python3 -m tdengine_mcp_server -h

用法: __main__.py [-h] [-th TAOS_HOST] [-tp TAOS_PORT] [-tu TAOS_USERNAME] [-pwd TAOS_PASSWORD] [-db TAOS_DATABASE] [-to TAOS_TIMEOUT] [-ll LOG_LEVEL]

TDengine MCP 服务器

选项:
  -h, --help            显示帮助信息并退出
  -th, --taos-host TAOS_HOST
                        TDengine 主机地址。默认值：`localhost`
  -tp, --taos-port TAOS_PORT
                        TDengine 端口号。默认值：`6041`
  -tu, --taos-username TAOS_USERNAME
                        TDengine 用户名。默认值：`root`
  -pwd, --taos-password TAOS_PASSWORD
                        TDengine 密码。默认值：`taosdata`
  -db, --taos-database TAOS_DATABASE
                        TDengine 数据库名称。默认值：`default`
  -to, --taos-timeout TAOS_TIMEOUT
                        TDengine 连接超时时间。默认值：`30`
  -ll, --log-level LOG_LEVEL
                        日志级别。默认值：`INFO`
  -trans, --transport {sse,stdio}
                        要使用的传输方式。默认值：`sse`

与 AI 助手集成

您的 AI 助手可以通过 MCP 服务器与 TDengine 数据库交互。这里有一些示例：

示例查询：

你能使用查询工具给我展示数据库中的前10条记录吗？

我需要分析我们的销售数据。你能运行一个 SQL 查询来获取上个月开发数据库中的每个地区的总销售额吗？

你能列出我们所有的可用数据库吗？

使用 TDengine MCP 工具

TDengine 查询 MCP 服务器提供了三个主要工具，您的 AI 助手可以使用这些工具：

1. 查询

对特定稳定执行只读 SQL 查询：

使用查询工具运行：

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

2. 信息

获取关于您的稳定的详细信息：

使用信息工具检查指定稳定的元信息。

DESCRIBE disks_info;

安全注意事项

• ✅ 只允许执行只读查询（SELECT, SHOW, DESCRIBE）

故障排除

连接问题

如果您遇到连接问题：

1. 核实您的 MCP 配置中的数据库凭据
2. 确保 TDengine 服务器正在运行且可访问
3. 检查是否有防火墙规则阻止连接
4. 通过在配置中设置 LOG_LEVEL 启用调试模式

常见错误

错误：查询执行失败

• 核实您的 SQL 语法
• 确认您仅使用了支持的查询类型（SELECT, SHOW, DESCRIBE）
• 确保您的查询确实是只读的

贡献

欢迎贡献！请随时提交拉取请求。

---

如需更多信息或支持，请在 GitHub 存储库中打开一个问题。