apache/iotdb-mcp-server

English | 中文
Overview
A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through IoTDB. This server enables running SQL queries and interacting with IoTDB using different SQL dialects (Tree Model and Table Model).
Components
Resources
The server doesn't expose any resources.
Prompts
The server doesn't provide any prompts.
Permission Model
IoTDB MCP permissions are advisory by default. The server reports the required
permission, risk level, and confirmation parameter for SQL actions, while the
host agent system owns user approval. Use inspect_sql_permission before
executing DDL/DML or destructive SQL when the tool is available.
Long-running hosted agents can provide full-permission defaults with
environment variables such as IOTDB_SQL_DRIVER_MODE=full and
TIMESEEK_MCP_PERMISSION_ENFORCEMENT=advisory. Set
TIMESEEK_MCP_PERMISSION_ENFORCEMENT=strict only when the MCP server itself
should hard-block disallowed operations.
Session policy changes are bounded by a deployment policy frozen at startup
(process environment > MCP configuration > defaults). Narrowing applies immediately;
widening within that ceiling requires out-of-band administrator approval by default.
IOTDB_SESSION_POLICY_APPROVAL_MODE=allow explicitly permits in-ceiling widening
without approval. Neither setting allows tools to change enforcement switches,
SQL classification prefixes, or the deployment ceiling. Reset and replace follow
the same rules. See session policy administration
for configuration, approval commands, and the required host isolation.
Tools
The server offers different tools for IoTDB Tree Model and Table Model. You can choose between them by setting the "IOTDB_SQL_DIALECT" configuration to either "tree" or "table".
Dialect-specific identifier semantics:
- Tree dialect:
- FROM targets use explicit root... paths.
- Projection expressions should usually use measurement names instead of full root... paths.
- IOTDB_DATABASE is only a connection/session hint; tree SQL still needs explicit root paths.
- Table dialect:
- FROM targets use table names in the current database.
- Projection expressions use column names.
Tree Model
- metadata_query
- Execute SHOW/COUNT queries to read metadata from the database
- Input:
- query_sql (string): The SHOW/COUNT SQL query to execute
- Supported query types:
- SHOW DATABASES [path]
- SHOW TIMESERIES [path]
- SHOW CHILD PATHS [path]
- SHOW CHILD NODES [path]
- SHOW DEVICES [path]
- COUNT TIMESERIES [path]
- COUNT NODES [path]
- COUNT DEVICES [path]
- Returns: Query results as array of objects
- select_query
- Execute SELECT queries to read data from the database
- Input:
- query_sql (string): The SELECT SQL query to execute (using TREE dialect, time using ISO 8601 format, e.g. 2017-11-01T00:08:00.000)
- Supported functions:
- SUM, COUNT, MAX_VALUE, MIN_VALUE, AVG, VARIANCE, MAX_TIME, MIN_TIME, etc.
- Returns: Query results as array of objects
- sql_executor_batch
- Execute multiple readonly SQL statements in parallel and store each result in ResultStore
- Input:
- sqls (array): Explicit single SQL statements, or
- sql_template + param_sets: Repeated SQL template with parameter objects
- max_concurrency (integer): Concurrent statement limit, default 4
- worker_pool_size (integer): Thread worker pool size, default follows concurrency and is capped by IOTDB_SQL_EXECUTOR_BATCH_MAX_WORKER_POOL_SIZE (default 16)
- per_item_timeout_ms (integer): Per-statement wait timeout, default 60000
- batch_timeout_ms (integer): Whole-batch wait timeout, default 300000
- max_result_rows_per_item / max_result_bytes_per_item: Per-statement result quota, defaults 10000 rows and 16 MiB
- max_batch_result_rows / max_batch_result_bytes: Whole-batch result quota, defaults 100000 rows and 64 MiB
- Template placeholders:
- {{name}} for SQL literals, {{name:path}} for IoTDB paths, {{name:identifier}} for SQL identifiers