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-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

以获取使用说明。

配置选项

.env 文件

命令行用法

$ 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`

与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查询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 仓库中打开一个 issue。