TDengine Query MCP Server

TDengine Query MCP Server

A Model Context Protocol (MCP) server that provides read-only TDengine database queries for AI assistants. Execute queries, explore database structures, and investigate your data directly from your AI-powered tools.

Supported AI Tools

This MCP server works with any tool that supports the Model Context Protocol, including:

• Cursor IDE: Set up in .cursor/mcp.json
• Anthropic Claude: Use with a compatible MCP client
• Other MCP-compatible AI assistants: Follow the tool's MCP configuration instructions

Features & Limitations

What It Does

• ✅ Execute read-only TDengine queries (SELECT, SHOW, DESCRIBE only)
• ✅ Provide database/stable information and metadata
• ✅ List available database and stables

What It Doesn't Do

• ❌ Execute write operations (INSERT, UPDATE, DELETE, CREATE, ALTER, etc.)
• ❌ Provide database design or schema generation capabilities
• ❌ Function as a full database management tool

This tool is designed specifically for data investigation and exploration through read-only queries. It is not intended for database administration, schema management, or data modification.

How to use

Run from source code

The recommended way to use this MCP server is to run it directly with uv without installation. This is how both Claude Desktop and Cursor are configured to use it in the examples below.

If you want to clone the repository:

git clone https://github.com/Abeautifulsnow/tdengine-mcp.git
cd tdengine-mcp

Then you can run the server directly:

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

Alternatively you can change the .env file in the src/tdengine_mcp_server/ directory to set the environment variables and run the server with the following command:

uv run src/tdengine_mcp_server

Important: the .env file will have higher priority than the command line arguments.

Install From Pypi by pip command

# Install globally with pip
pip install tdengine_mcp_server

and then run:

python -m tdengine_mcp_server -h

Install by uvx command

uvx tdengine-mcp-server -h

Install From smithery by npx command

npx -y @smithery/cli@latest install @Abeautifulsnow/tdengine-mcp --client cursor --config '"{}"'

You can change the client after the --client option with alternatives claude, 'windsurf' and so on. Also you can refer to this: smithery/tdengine-mcp-server

Configuration Options

.env file

Environment Variable	Description	Default
LOG_LEVEL	Set the log level (DEBUG, INFO, WARN, ERROR)	INFO
TDENGINE_HOST	Database host for environment	localhost
TDENGINE_PORT	Database port	6041
TDENGINE_USERNAME	Database username	root
TDENGINE_PASSWORD	Database password	taosdata
TDENGINE_DATABASE	Database name	log
TDENGINE_TIMEOUT	Set the connection timeout in seconds	30
TRANSPORT	Control the transport to use	stdio

cli usage

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

Integration with AI Assistants

Your AI assistant can interact with TDengine databases through the MCP server. Here are some examples:

Example queries:

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?

Using TDengine MCP Tools

The TDengine Query MCP server provides three main tools that your AI assistant can use:

1. query

Execute read-only SQL queries against a specific stable:

Use the query tool to run:

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

2. info

Get detailed information about your stable:

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

DESCRIBE disks_info;

Security Considerations

• ✅ Only read-only queries are allowed (SELECT, SHOW, DESCRIBE)

Troubleshooting

Connection Issues

If you're having trouble connecting:

1. Verify your database credentials in your MCP configuration
2. Ensure the TDengine server is running and accessible
3. Check for firewall rules blocking connections
4. Enable debug mode by setting LOG_LEVEL in your configuration

Common Errors

Error: Query execution failed

• Verify your SQL syntax
• Check that you're only using supported query types (SELECT, SHOW, DESCRIBE)
• Ensure your query is truly read-only

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

For more information or support, please open an issue on the GitHub repository.