# Mcp Tdengine Tsdb

> MCP Server for TDengine TSDB

- **Type:** MCP server
- **Install:** `agentstack add mcp-taosdata-mcp-tdengine-tsdb`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [taosdata](https://agentstack.voostack.com/s/taosdata)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [taosdata](https://github.com/taosdata)
- **Source:** https://github.com/taosdata/mcp-tdengine-tsdb

## Install

```sh
agentstack add mcp-taosdata-mcp-tdengine-tsdb
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-tdengine-tsdb

English | [简体中文](README-CN.md)

## Table of Contents

- [1. Introduction](#1-introduction)
- [2. Documentation](#2-documentation)
- [3. Prerequisites](#3-prerequisites)
- [4. Build](#4-build)
- [5. Testing](#5-testing)
  - [5.1 Test Execution](#51-test-execution)
  - [5.2 Test Case Addition](#52-test-case-addition)
  - [5.3 Performance Testing](#53-performance-testing)
- [6. CI/CD](#6-cicd)
- [7. Submitting Issues](#7-submitting-issues)
- [8. Submitting PRs](#8-submitting-prs)
- [9. References](#9-references)
- [10. License](#10-license)

## 1. Introduction

MCP Server for TDengine TSDB provides a complete set of tools for querying, managing, and monitoring TDengine time-series database.

### Core Tools

- **Query Tool (query)** - Execute TDengine SELECT queries and return results
- **Show Tool (show)** - Execute various SHOW commands to query metadata, supporting multiple parameter options
- **Info Tool (info)** - Provide TDengine server information, including version, status, etc.
- **Describe Table Tool (describe_table)** - Describe the structure of a specified table
- **Predefined Schema Overview Tool (get_schema_overview)** - Get database structure overview information

### Technical Features

- Developed in Go language, lightweight and efficient
- Uses TDengine WebSocket driver to connect to the database
- Supports configuration via command line parameters and environment variables
- CSV format result output

## 2. Documentation

### Configuration Options

| Parameter                 | Environment Variable             | Default Value | Description                                                                             |
|:--------------------------|:---------------------------------|:--------------|:----------------------------------------------------------------------------------------|
| `--host`                  | `TDENGINE_HOST`                  | `localhost`   | TDengine hostname                                                                       |
| `--port`                  | `TDENGINE_PORT`                  | `6041`        | TDengine port (taosAdapter port)                                                        |
| `--user`                  | `TDENGINE_USER`                  | `root`        | TDengine username                                                                       |
| `--pass`                  | `TDENGINE_PASS`                  | `taosdata`    | TDengine password                                                                       |
| `--db`                    | `TDENGINE_DB`                    |               | TDengine database name                                                                  |
| `--dsn`                   | `TDENGINE_DSN`                   |               | TDengine Data Source Name (DSN), higher priority than individual connection parameters  |
| `--schema_overview_file`  | `TDENGINE_SCHEMA_OVERVIEW_FILE`  |               | Predefined database schema overview file path                                           |

### Usage Instructions

#### Installation

1. Download the latest [release](https://github.com/taosdata/mcp-tdengine-tsdb/releases)
2. Place the executable in your system's `$PATH` or in an easily accessible location.
3. Alternatively, if you have Go installed, you can build from source using:

```bash
go install -v github.com/taosdata/mcp-tdengine-tsdb@latest
```

#### Configuring MCP

Example of adding to MCP configuration file:

```json
{
  "mcpServers": {
    "tdengine-tsdb": {
      "command": "mcp-tdengine-tsdb",
      "args": [
        "--host", "localhost",
        "--port", "6041",
        "--user", "root",
        "--pass", "taosdata",
        "--db", "test"
      ]
    }
  }
}
```

- `command`: Specify the executable name or path
- `args`: List of parameters passed to the executable

## 3. Prerequisites

- Go 1.24.12 environment
- TDengine database 3.3.6.0 or higher
- Git version control tool

## 4. Build

### Clone Repository

```bash
git clone https://github.com/taosdata/mcp-tdengine-tsdb.git
cd mcp-tdengine-tsdb
```

### Build Project

```bash
go build -o mcp-tdengine-tsdb
```

## 5. Testing

**Tests will operate on the `test` database, which will be deleted after testing. Please ensure the `test` database does not contain important data.**

### 5.1 Test Execution

1. Before running tests, ensure that the TDengine server is installed and that `taosd` and `taosAdapter` are running.
   The database should be empty.
2. In the project directory, run `go test ./...` to execute the tests. The tests will connect to the local TDengine
   server and taosAdapter for testing.
3. The output result `PASS` means the test passed, while `FAIL` means the test failed. For detailed information, run
   `go test -v ./...`.

### 5.2 Test Case Addition

Add test cases to the `*_test.go` file to ensure that the test cases cover the new code.

### 5.3 Performance Testing

Performance testing is in progress.

## 6. CI/CD

The project uses GitHub Actions for continuous integration and continuous deployment (CI/CD), with configuration files located at `.github/workflows/build.yml`.

When code is pushed to the `main` branch or a pull request is created for the `main` branch, the CI workflow will automatically trigger, executing automated builds and tests.

## 7. Submitting Issues

We welcome submitting [GitHub Issues](https://github.com/taosdata/mcp-tdengine-tsdb/issues/new?template=Blank+issue). When submitting, please include the following information:

- Problem description
- Reproduction steps
- Expected behavior
- Actual behavior
- Environment information
- Related screenshots or logs

## 8. Submitting PRs

We welcome developers to contribute to this project. When submitting PRs, please follow these steps:

1. Fork this project. Please refer
   to [how to fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
2. Create a new branch from the main branch with a meaningful branch name (`git checkout -b my_branch`).
3. Modify the code, ensure all unit tests pass, and add new unit tests to verify the changes.
4. Push the changes to the remote branch (`git push origin my_branch`).
5. Create a Pull Request on GitHub. Please refer
   to [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. After submitting the PR, you can find your PR through
   the [Pull Request](https://github.com/taosdata/mcp-tdengine-tsdb/pulls). Click on the corresponding link to see if the CI for
   your PR has passed. If it has passed, it will display "All checks have passed". Regardless of whether the CI passes
   or not, you can click "Show all checks" -> "Details" to view the detailed test case logs.
7. After submitting the PR, if the CI passes, you can find your PR on
   the [codecov](https://app.codecov.io/gh/taosdata/mcp-tdengine-tsdb/pulls) page to check the coverage.

## 9. References

- [TDengine Official Website](https://www.taosdata.com/)
- [TDengine GitHub](https://github.com/taosdata/TDengine)

## 10. License

[MIT License](./LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [taosdata](https://github.com/taosdata)
- **Source:** [taosdata/mcp-tdengine-tsdb](https://github.com/taosdata/mcp-tdengine-tsdb)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-taosdata-mcp-tdengine-tsdb
- Seller: https://agentstack.voostack.com/s/taosdata
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.