iotdb

IoTDB MCP Server provides tools to interact with an IoTDB instance using two SQL dialects: Tree Model and Table Model. You can run SHOW, COUNT, SELECT, and export operations against IoTDB via its MCP tools. Tree Model focuses on metadata and data queries using the TREE dialect, supporting commands like metadata_query (SHOW/COUNT queries), select_query (data reads with time in ISO format), and export_query (export results to CSV or Excel). Table Model provides schema-oriented and data-read capabilities, including read_query for data, list_tables and describe_table for schema discovery, and export_table_query for exporting results. To use, set the IOTDB_SQL_DIALECT environment variable to either tree or table, depending on the operation you intend to perform. Ensure IoTDB is reachable at the configured host/port and that authentication credentials are correct. You can invoke the MCP server through the uvx workflow or via your preferred integration (e.g., Claude Desktop) by specifying the server command and arguments as configured in your environment.

Prerequisites:

• Python environment with uvm (uv) package manager available
• IoTDB installed and accessible
• MCP server source code from the repository

1. Clone and prepare the environment

• git clone https://github.com/apache/iotdb-mcp-server.git
• cd iotdb-mcp-server

2. Create and activate a Python virtual environment

• uv venv
• source venv/bin/activate # Linux/macOS
• venv\Scripts\activate # Windows

3. Install development dependencies

• uv sync

4. Run the MCP server (example using uvx)

• uvx iotdb-mcp-server
• Ensure environment variables are set (see mcp_config) or supply them in your runtime environment.

5. Validate the server is reachable

• Use your preferred client or tooling to issue queries against the configured IoTDB instance.

Tips and common issues:

• Ensure IoTDB_HOST, IOTDB_PORT, IOTDB_USER, and IOTDB_PASSWORD are correctly set to access IoTDB.
• The IOTDB_SQL_DIALECT can be switched between 'tree' and 'table' to change the query model.
• For exporting results, ensure the IOTDB_EXPORT_PATH directory exists and is writable by the MCP server process.
• If you encounter connection timeouts, adjust timeout-related settings in your environment or increase IOTDB client retry behavior as needed.
• When running in Docker or cloud environments, map ports and ensure network access to IoTDB endpoints.
• The Python uv workflow may differ slightly depending on how the package is published; if using a local path, you might need to tweak the package-name argument to uvx accordingly.