https://github.com/taosdata/mcp-tdengine-tsdb
MCP Server for TDengine TSDB
https://github.com/taosdata/mcp-tdengine-tsdb
Last synced: 3 months ago
JSON representation
MCP Server for TDengine TSDB
- Host: GitHub
- URL: https://github.com/taosdata/mcp-tdengine-tsdb
- Owner: taosdata
- License: mit
- Created: 2026-01-22T09:42:09.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-23T15:16:37.000Z (5 months ago)
- Last Synced: 2026-02-15T20:25:42.581Z (4 months ago)
- Language: Go
- Size: 38.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README-CN.md
- License: LICENSE
Awesome Lists containing this project
README
# mcp-tdengine-tsdb
[English](README.md) | 简体中文
## 目录
- [1. 简介](#1-简介)
- [2. 文档](#2-文档)
- [3. 前置条件](#3-前置条件)
- [4. 构建](#4-构建)
- [5. 测试](#5-测试)
- [5.1 运行测试](#51-运行测试)
- [5.2 添加用例](#52-添加用例)
- [5.3 性能测试](#53-性能测试)
- [6. CI/CD](#6-cicd)
- [7. 提交 Issue](#7-提交-issue)
- [8. 提交 PR](#8-提交-pr)
- [9. 引用](#9-引用)
- [10. 许可证](#10-许可证)
## 1. 简介
MCP Server for TDengine TSDB，提供了一套完整的工具集，用于查询、管理和监控 TDengine 时序数据库。
### 核心工具
- **查询工具 (query)** - 执行 TDengine SELECT 查询并返回结果
- **显示工具 (show)** - 执行各种 SHOW 命令查询元数据，支持多种参数选项
- **信息工具 (info)** - 提供 TDengine 服务器信息，包括版本、状态等
- **描述表工具 (describe_table)** - 描述指定表的结构
- **预定义schema获取工具 (get_schema_overview)** - 获取数据库结构概览信息
### 技术特点
- 基于 Go 语言开发，轻量高效
- 使用 TDengine WebSocket 驱动连接数据库
- 支持通过命令行参数和环境变量配置
- CSV 格式结果输出
## 2. 文档
### 配置选项
| 参数 | 环境变量 | 默认值 | 描述 |
|:---------------------------|:------------------------------------|:---------------|:---------------------------------------------------------------------|
| `--host` | `TDENGINE_HOST` | `localhost` | TDengine 主机名 |
| `--port` | `TDENGINE_PORT` | `6041` | TDengine 端口（taosAdapter 端口） |
| `--user` | `TDENGINE_USER` | `root` | TDengine 用户名 |
| `--pass` | `TDENGINE_PASS` | `taosdata` | TDengine 密码 |
| `--db` | `TDENGINE_DB` | | TDengine 数据库名 |
| `--dsn` | `TDENGINE_DSN` | | TDengine 数据源名称 (DSN)，优先级高于单独的连接参数 |
| `--schema_overview_file` | `TDENGINE_SCHEMA_OVERVIEW_FILE` | | 预定义数据库schema概览文件路径 |
### 使用说明
#### 安装
1. 下载最新的 [release](https://github.com/taosdata/mcp-tdengine-tsdb/releases)
2. 将可执行文件放置在系统的 `$PATH` 中，或放在一个便于访问的位置。
3. 或者，如果你已经安装了 Go，可以通过以下命令从源代码构建：
```bash
go install -v github.com/taosdata/mcp-tdengine-tsdb@latest
```
#### 配置 MCP
添加到 MCP 配置文件中的示例：
```json
{
"mcpServers": {
"tdengine-tsdb": {
"command": "mcp-tdengine-tsdb",
"args": [
"--host", "localhost",
"--port", "6041",
"--user", "root",
"--pass", "taosdata",
"--db", "test"
]
}
}
}
```
- `command`：指定可执行文件名称或路径
- `args`：传递给可执行文件的参数列表
## 3. 前置条件
- Go 1.24.12 环境
- TDengine 数据库 3.3.6.0 及以上版本
- Git 版本控制工具
## 4. 构建
### 克隆仓库
```bash
git clone https://github.com/taosdata/mcp-tdengine-tsdb.git
cd mcp-tdengine-tsdb
```
### 构建项目
```bash
go build -o mcp-tdengine-tsdb
```
## 5. 测试
**测试将使用 `test` 数据库进行操作，测试完成后会删除此数据库，请确保 `test` 数据库不存在重要数据。**
### 5.1 运行测试
1. 执行测试前确保已经安装 TDengine 服务端，并且已经启动 taosd 与 taosAdapter，数据库干净无数据。
2. 项目目录下执行 `go test ./...` 运行测试，测试会连接到本地的 TDengine 服务器与 taosAdapter 进行测试。
3. 输出结果 `PASS` 为测试通过，`FAIL` 为测试失败，查看详细信息需要执行 `go test -v ./...`。
### 5.2 添加用例
在 `*_test.go` 文件中添加测试用例，确保测试用例覆盖到新增的代码。
### 5.3 性能测试
性能测试还在开发中。
## 6. CI/CD
项目使用 GitHub Actions 进行持续集成和持续部署 (CI/CD)，配置文件位于 `.github/workflows/build.yml`。
当代码推送到 `main` 分支或创建针对 `main` 分支的拉取请求时，CI 工作流将自动触发，执行自动化构建和测试。
## 7. 提交 Issue
我们欢迎提交 [GitHub Issue](https://github.com/taosdata/mcp-tdengine-tsdb/issues/new?template=Blank+issue)。 提交时请说明下面信息：
- 问题描述
- 复现步骤
- 预期行为
- 实际行为
- 环境信息
- 相关截图或日志
## 8. 提交 PR
我们欢迎开发者一起开发本项目，提交 PR 时请参考下面步骤：
1. Fork 本项目，请参考 ([how to fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo))。
2. 从 main 分支创建一个新分支，请使用有意义的分支名称 (`git checkout -b my_branch`)。
3. 修改代码，保证所有单元测试通过，并增加新的单元测试验证修改。
4. 提交修改到远端分支 (`git push origin my_branch`)。
5. 在 GitHub 上创建一个 Pull
Request ([how to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request))。
6. 提交 PR 后，可以通过 [Pull Request](https://github.com/taosdata/mcp-tdengine-tsdb/pulls) 找到自己的 PR，点击对应链接进去可以看到自己
PR CI 是否通过，如果通过会显示 “All checks have passed”。无论 CI 是否通过，都可以点击 “Show all checks” -> “Details”
来查看详细用例日志。
7. 提交 PR 后，如果 CI 通过，可以在 [codecov](https://app.codecov.io/gh/taosdata/mcp-tdengine-tsdb/pulls) 页面找到自己 PR 查看覆盖率。
## 9. 引用
- [TDengine 官网](https://www.taosdata.com/)
- [TDengine GitHub](https://github.com/taosdata/TDengine)
## 10. 许可证
[MIT License](./LICENSE)