Content
# TDengine Query MCP Server
[](https://opensource.org/licenses/MIT)
[](https://smithery.ai/server/@Abeautifulsnow/tdengine-mcp)
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:
```bash
git clone https://github.com/Abeautifulsnow/tdengine-mcp.git
cd tdengine-mcp
```
Then you can run the server directly:
```bash
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:
```bash
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
```bash
# Install globally with pip
pip install tdengine_mcp_server
```
and then run:
```bash
python -m tdengine_mcp_server -h
```
### Install by `uvx` command
```bash
uvx tdengine-mcp-server -h
```
### Install From smithery by `npx` command
```bash
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](https://smithery.ai/server/@Abeautifulsnow/tdengine-mcp)
## 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
```text
$ 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](https://github.com/Abeautifulsnow/tdengine-mcp/issues) on the GitHub repository.
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
markitdown
Python tool for converting files and office documents to Markdown.
firecrawl
Firecrawl MCP Server enables web scraping, crawling, and content extraction.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.
mempalace
The highest-scoring AI memory system ever benchmarked. And it's free.