Apache IoTDB MCP Server and Tools

Overview

Apache IoTDB MCP Server implements a Model Context Protocol (MCP) adapter that exposes IoTDB database operations and business-intelligence style interactions through a small server and toolset. It supports two SQL dialects — the Tree Model (IoTDB native hierarchical view) and the Table Model (relational-like queries) — so client applications can run metadata queries, SELECTs, and export results without embedding IoTDB client code.

This server is intended for developers and operators who want a lightweight programmatic layer for monitoring, schema exploration, querying, and exporting time-series data from IoTDB. It simplifies connection management, provides sensible defaults for performance (connection pooling, fetch size, timeouts), and can be integrated into local workflows or tools such as Claude Desktop.

Features

• Dual SQL dialect support: Tree Model and Table Model
• Metadata and data query tools (SHOW, COUNT, SELECT, etc.)
• Export query results to CSV or Excel with a preview
• Session pool management and automatic reconnection
• Configurable via environment variables or command-line flags
• Lightweight dev workflow (Python, virtualenv) and integration examples

Installation / Configuration

Prerequisites:

• Python 3.x
• IoTDB instance reachable from the host
• uv (universe package manager) for development tasks (optional for production)

Clone and set up the project for development:

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

# Create virtual environment and activate (using uv)
uv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# Install development dependencies
uv sync

Run the server directly (example using uv):

IOTDB_HOST=127.0.0.1 IOTDB_PORT=6667 IOTDB_USER=root IOTDB_PASSWORD=root \
IOTDB_SQL_DIALECT=table uv --directory src/iotdb_mcp_server run server.py

Or pass same settings as CLI flags:

uv --directory src/iotdb_mcp_server run server.py --host 127.0.0.1 --port 6667 --user root --password root --sql-dialect table

Configuration options

Available Tools

The server exposes tool-like endpoints (used by MCP clients) organized by dialect.

Tree Model tools

• metadata_query
  • Purpose: Run SHOW / COUNT style metadata queries (SHOW TIMESERIES, SHOW DEVICES, COUNT TIMESERIES, etc.)
  • Input: query_sql (string)
  • Output: array of objects (rows) representing metadata
• select_query
  • Purpose: Run SELECT queries in Tree dialect (time as ISO 8601)
  • Input: query_sql (string)
  • Output: array of objects with time and fields; supports aggregation functions (SUM, COUNT, AVG, MAX_VALUE, MIN_TIME, etc.)
• export_query
  • Purpose: Execute a query and write CSV/Excel file
  • Input: query_sql (string), format (“csv” or “excel”), optional filename
  • Output: export metadata (path, name) and a preview of up to 10 rows

Table Model tools

• read_query
  • Purpose: Run SELECT queries using TABLE dialect (relational view)
  • Input: query_sql (string)
  • Output: array of objects (rows)
• list_tables
  • Purpose: Return all table names
  • Input: none
  • Output: array of table names
• describe_table
  • Purpose: Return column definitions and types for a given table
  • Input: table_name (string)
  • Output: array of column schema objects
• export_table_query
  • Purpose: Export a TABLE-dialect query to CSV or Excel
  • Input: query_sql, format, optional filename
  • Output: export metadata + preview

Example Tree SELECT (time in ISO 8601):

SELECT temperature, humidity FROM root.sg1.d1 WHERE time >= '2023-01-01T00:00:00.000' AND time < '2023-01-02T00:00:00.000'

Example Table SELECT:

SELECT time, device_id, value FROM measurements WHERE device_id='sensor-01' ORDER BY time DESC LIMIT 100

Performance & Reliability

• Session pool with configurable maximum sessions (supports up to 100 sessions)
• Optimized fetch size (default 1024 rows per fetch)
• Automatic connection retry logic on transient failures
• Session wait and operation timeouts (default ~5000 ms) to avoid long blocking operations
• Export operations stream results to disk to reduce memory pressure

Use Cases

• Schema discovery: use metadata_query (Tree) or list_tables/describe_table (Table) to build dynamic dashboards or schema explorers.
• Ad-hoc analytics: run read_query/select_query to fetch time-series slices, apply aggregates, and return JSON-ready results for visualization.
• Scheduled exports: run export_query/export_table_query from a script or scheduler to produce daily CSV/Excel snapshots for downstream pipelines.
• Integration with tools: wire the MCP server into Claude Desktop (or other MCP clients) so non-developers can run queries and export data without direct DB credentials.

Example: export last 24 hours of a timeseries to CSV (Tree dialect)

• Call export_query with format=“csv” and a SELECT filtering time >= now()-1d
• Server writes CSV to IOTDB_EXPORT_PATH and returns file name + preview

Integration & Support

• GitHub repository and issues: https://github.com/apache/iotdb-mcp-server
• Claude Desktop: include an MCP server entry in claude_desktop_config.json pointing at the server command and env vars (the repo includes example configuration snippets).

For problems or feature requests, open an issue on the project repository.