Tdengine MCP

🚀 TDengine Query MCP Server

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

🚀 Quick Start

This MCP server is designed to offer read - only TDengine database query services for AI assistants. With it, you can execute queries, explore the database structure, and investigate data directly from your AI tools.

✨ Features

Supported AI Tools

This MCP server can be used with any tool that supports the Model Context Protocol, including:

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

Features and Limitations

Functions

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

Unsupported Functions

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

This tool is designed for data investigation and exploration and is limited to read - only queries. It is not for database management, schema management, or data modification.

📦 Installation

Run from Source Code

The recommended way is to run directly from the source code using uv without installation. This is how it is configured in the Claude Desktop and Cursor examples.

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

Or you can modify the .env file in the src/tdengine_mcp_server/ directory to set environment variables and then run the server using the following command:

uv run src/tdengine_mcp_server

⚠️ Important Note

By default, the database name is default.

Install via pip

You can also install it using the Python package:

pip install tdengine-mcp-server

Then start the server:

tdengine-mcp-server --config your_config_file.yaml

💻 Usage Examples

Basic Usage

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

Sample Queries

Can you use the query tool to display the first 10 records in the database?

I need to analyze our sales data. Can you run an SQL query to get the total sales by region from the development database last month?

Can you list all our available databases?

Using TDengine Query MCP Tools

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

1. query

Execute a read - only SQL query on a specific stable table:

Use the query tool to run the following command:

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

2. info

Get detailed information about a specified stable table:

Use the info tool to check the metadata of the specified stable.

DESCRIBE disks_info;

🔧 Technical Details

Security Considerations

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

Troubleshooting

Connection Issues

If you encounter connection problems:

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

Common Errors

Error: Query execution failed

• Verify your SQL syntax.
• Ensure that only supported query types (SELECT, SHOW, DESCRIBE) are used.
• Ensure that your query is indeed read - only.

🤝 Contribution

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

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