home / mcp / tdengine query mcp server

TDengine Query MCP Server

TDengine MCP Server.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "abeautifulsnow-tdengine-mcp": {
      "command": "uv",
      "args": [
        "run",
        "src/tdengine_mcp_server",
        "-th",
        "192.100.8.22",
        "-db",
        "log",
        "-ll",
        "debug"
      ],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "TRANSPORT": "stdio",
        "TDENGINE_HOST": "localhost",
        "TDENGINE_PORT": "6041",
        "TDENGINE_TIMEOUT": "30",
        "TDENGINE_DATABASE": "log",
        "TDENGINE_PASSWORD": "taosdata",
        "TDENGINE_USERNAME": "root"
      }
    }
  }
}

TDengine Query MCP Server provides read-only access to TDengine data for AI assistants. You can execute safe queries, explore database structures, and inspect data metadata directly from your AI tools, without the ability to modify anything.

How to use

You connect your MCP client (such as Cursor IDE, Claude, or any MCP-enabled AI assistant) to the TDengine Query MCP Server to run read-only queries. Start with a local, running MCP server instance and then issue simple read operations like listing databases or retrieving data from a stable. Use the built-in tools to run queries against a specific stable and to fetch metadata for any stable you need to inspect.

How to install

Prerequisites: you need Node.js available in your environment to run the MCP server locally. You also need a TDengine server accessible for the read-only queries.

Option A: Run from source code directly with the provided runtime command.

Complete command to start from source with explicit TDengine target and log level:

uv run src/tdengine_mcp_server -th 192.100.8.22 -db log -ll debug

Alternative: start without additional target options; if you prefer, you can set environment variables in the environment and run the server with the same entry point.

Additional configuration and usage notes

Configuration options are designed to be straightforward. You can optionally run the server from source with the environment-based configuration or use direct command-line options to specify the TDengine host, port, database, and timeouts as shown above.

Security considerations

Only read-only operations are permitted. You can execute SELECT, SHOW, and DESCRIBE queries, but you cannot perform INSERT, UPDATE, DELETE, CREATE, ALTER, or other write actions.

Troubleshooting

If you run into connection issues, verify TDengine credentials and that the TDengine server is reachable. Ensure there are no firewall blocks, and enable debug logging by setting the log level to DEBUG.

Common errors typically involve invalid SQL or attempting disallowed operations. Ensure your queries are read-only and correctly formed for the target stable.

Tools and endpoints

Your AI assistant uses two main tools to interact with TDengine MCP Server:

query: Run read-only SQL against a specified stable, for example retrieving data rows or computing aggregates.

info: Retrieve metadata and structure information about a stable, such as table descriptions.

Notes

The server focuses on data investigation and exploration through safe read-only queries. It is not a full database administration or schema-management tool.

Available tools

query

Execute read-only SQL queries against a specific stable, returning result rows or aggregates.

info

Retrieve detailed metadata about a stable, including table structures and descriptors.