TDengine Query MCP Server

TDengine 查询 MCP 服务

一个 Model Context Protocol（MCP）服务，为 AI 助手提供只读 TDengine 数据库查询功能。可直接通过 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-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

重要提示：.env 文件的优先级高于命令行参数。

使用 pip 命令从 Pypi 安装

# Install globally with pip
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

usage: __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 Server

options:
  -h, --help            show this help message and exit
  -th, --taos-host TAOS_HOST
                        TDengine host address. Default: `localhost`
  -tp, --taos-port TAOS_PORT
                        TDengine port number. Default: `6041`
  -tu, --taos-username TAOS_USERNAME
                        TDengine username. Default: `root`
  -pwd, --taos-password TAOS_PASSWORD
                        TDengine password. Default: `taosdata`
  -db, --taos-database TAOS_DATABASE
                        TDengine database name. Default: `default`
  -to, --taos-timeout TAOS_TIMEOUT
                        TDengine connection timeout. Default: `30`
  -ll, --log-level LOG_LEVEL
                        Log level. Default: `INFO`
  -trans, --transport {sse,stdio}
                        The transport to use. Default: `sse`

与 AI 助手集成

AI 助手可以通过 MCP 服务与 TDengine 数据库交互。以下是一些示例：

示例查询：

Can you use the query tool to show me the first 10 records from the database?

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you list all the available databases we have?

使用 TDengine MCP 工具

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

1. query

对指定的超级表执行只读 SQL 查询：

Use the query tool to run:

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

2. info

获取超级表的详细信息：

Use the info tool to check the meta info about the specified stable.

DESCRIBE disks_info;

安全注意事项

• ✅ 仅允许只读查询（SELECT、SHOW、DESCRIBE）

故障排除

连接问题

如果连接遇到问题：

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

常见错误

错误：查询执行失败

• 检查 SQL 语法
• 确认仅使用受支持的查询类型（SELECT、SHOW、DESCRIBE）
• 确保查询确实为只读

贡献

欢迎贡献！请随时提交 Pull Request。

---

如需了解更多信息或获取支持，请在 GitHub 仓库中提出问题。