TDengine Query MCP Service Gateway

This package establishes an observation-only conduit for TDengine data access via the Model Context Protocol (MCP), intended for integration with intelligent automation systems. Utilize it to inspect schemas, explore datasets, and retrieve factual information directly within your AI environment.

Compatible AI Environments

This MCP gateway is operable with any platform adhering to the Model Context Protocol specification, including:

• Cursor IDE: Configuration via .cursor/mcp.json is standard.
• Anthropic Claude: Requires a compatible MCP client implementation.
• Other MCP Services: Refer to the respective tool's documentation for configuration parameters.

Core Functionality & Constraints

Permitted Actions

• ✅ Execution of read-only TDengine SQL commands (restricted to SELECT, SHOW, DESCRIBE).
• ✅ Provision of metadata concerning databases and their respective tables (stables).
• ✅ Utility for enumerating existing databases and tables.

Forbidden Actions

• ❌ Any form of data mutation (e.g., INSERT, UPDATE, DELETE, schema manipulation like CREATE/ALTER).
• ❌ Automated generation of database schemas or DDL statements.
• ❌ Functionality as a comprehensive database administration utility.

This service is strictly purposed for non-destructive data investigation and insight extraction. It explicitly prohibits administrative tasks or any operation leading to data state changes.

Deployment Instructions

Execution from Source Repository

The suggested deployment method involves executing the server using uv directly, bypassing traditional installation steps, which aligns with common configurations for Claude Desktop and Cursor setups.

If cloning the source repository is necessary:

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

Then, start the service:

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

Alternatively, modify environment variables within the .env file located at src/tdengine_mcp_server/ before launching:

bash uv run src/tdengine_mcp_server

Crucial Note: Environment variables defined in the .env file will override any values passed via command-line arguments.

Installation via Pip

bash

Global installation

pip install tdengine_mcp_server

Followed by execution:

bash python -m tdengine_mcp_server -h

Installation via uvx

bash uvx tdengine-mcp-server -h

Installation via Smithery (npx)

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

You can substitute 'cursor' with other supported clients like 'claude', 'windsurf', etc. Further details are available at: smithery/tdengine-mcp-server

Configuration Parameters

Environment Variables (.env)

Variable Name	Purpose	Default Value
LOG_LEVEL	Sets verbosity (DEBUG, INFO, WARN, ERROR)	INFO
TDENGINE_HOST	Address of the database server	localhost
TDENGINE_PORT	Network port for communication	6041
TDENGINE_USERNAME	Authentication ID	root
TDENGINE_PASSWORD	Authentication secret	taosdata
TDENGINE_DATABASE	Target default schema/database	log
TDENGINE_TIMEOUT	Connection timeout duration (seconds)	30
TRANSPORT	Communication protocol layer	stdio

Command Line Interface (CLI) Syntax

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 Display this assistance 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 user identity. Default: root -pwd, --taos-password TAOS_PASSWORD TDengine secret key. Default: taosdata -db, --taos-database TAOS_DATABASE Target TDengine schema name. Default: default -to, --taos-timeout TAOS_TIMEOUT Time limit for TDengine connection attempts. Default: 30 -ll, --log-level LOG_LEVEL Severity level for logging. Default: INFO -trans, --transport {sse,stdio} Selection for I/O mechanism. Default: sse

AI Assistant Interaction Examples

Your designated AI agent can interface with TDengine data via this service. Sample interaction prompts:

Can you utilize the query tool to present the initial 10 rows from the current database context?

I need to perform an analysis on transactional records. Instruct the SQL tool to aggregate total revenue segmented by geographical area for the previous calendar month, targeting the 'production' schema.

Please generate a listing of all accessible data repositories.

Utilizing TDengine MCP Toolset

The TDengine Query MCP service exposes distinct capabilities for agent invocation:

1. query Utility

Used for running standard, non-modifying SQL queries against a specified table (stable):

Invoke the query utility to execute:

SELECT sensor_id, temperature FROM weather_readings WHERE ts > '2025-01-01 12:00:00' ORDER BY ts DESC LIMIT 10;

2. info Utility

Retrieves structural metadata for a named stable:

Call the info utility to examine the metadata structure for the table named 'system_health_metrics'.

DESCRIBE system_health_metrics;

Safety Guarantees

• ✅ Access is strictly limited to read operations (SELECT, SHOW, DESCRIBE).

Debugging & Support

Connectivity Diagnostics

If connection establishment fails:

1. Confirm authentication credentials are correct in your MCP setup.
2. Validate that the TDengine server process is active and reachable.
3. Inspect any intervening network firewall configurations.
4. Activate verbose logging by setting the LOG_LEVEL environment variable to DEBUG.

Common Failures

Error: Query execution failed

• Scrutinize the structure of your supplied SQL statement.
• Reconfirm that the operation strictly adheres to permitted query types (SELECT, SHOW, DESCRIBE).
• Ensure the query intent is purely for data retrieval, not modification.

Contribution Guidelines

We welcome external contributions! Please feel free to file a Pull Request with your enhancements.

---

For support or detailed inquiries, please initiate a new issue on the project's GitHub repository.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea