IoTDB MCP Services

This directory contains tool modules registered by src/iotdb_mcp_server/server.py.

Registration Overview

Current registration order:

register_target_tools
register_runtime_policy_tools
register_result_store_tools
register_query_tools
register_sql_driver_tools
register_metadata_tools
register_explain_tools
register_database_tools
register_timeseries_tools
register_ttl_tools
register_table_tools
register_udf_tools
register_write_tools
register_model_tools

Tool Matrix

`query.py`

Tree dialect:
- select_query(query_sql, max_inline_rows=None, page_size_rows=None)
- export_query(query_sql, format="csv", filename=None)
Table dialect:
- read_query(query_sql, max_inline_rows=None, page_size_rows=None)
- export_table_query(query_sql, format="csv", filename=None)

Read-query tools stream rows into ResultStore and return only a preview by default. Use the returned result_id and next_cursor with read_result_page.

`results.py`

read_result_page(result_id, cursor=None, offset=None, limit=None, owner_session_id=None, target_id=None)
read_result_pages(pages, owner_session_id=None, default_limit=None, max_pages=None, max_total_rows=None, continue_on_error=True, target_id=None)
list_result_store(owner_session_id=None, all_sessions=False, limit=50, target_id=None)
cleanup_result_store(owner_session_id=None, all_sessions=False, ttl_seconds=None, target_id=None)
delete_result(result_id, owner_session_id=None, all_sessions=False, target_id=None)

Loads a bounded page from a file-backed ResultStore result. Pass the same target_id as the original query when multiple IoTDB targets are registered. When the TimeSeek Codex plugin hook is active, owner_session_id is injected from the Codex session. Standalone MCP usage can pass owner_session_id explicitly or set TIMESEEK_MCP_SESSION_ID; otherwise the ResultStore owner is standalone.

ResultStore cleanup is finite and session-aware. Each write runs lightweight cleanup for the current owner and then enforces global limits. Entries expire by last_accessed_at, and quota pressure evicts least-recently-accessed results. If a single new result is larger than the byte quota, it is retained so the caller can still page through the result that was just returned.

read_result_pages batches multiple page requests in one MCP call. Each item accepts result_id plus optional cursor, offset, limit, and owner_session_id. The default per-call limits are 32 pages and 10000 returned rows; override them with tool arguments or TIMESEEK_RESULT_MAX_BATCH_PAGES and TIMESEEK_RESULT_MAX_BATCH_READ_ROWS.

`sql_driver.py`

Both dialects:
- sql_driver_policy()
- inspect_sql_permission(sql)
- sql_executor_batch(sqls=None, sql_template=None, param_sets=None, max_concurrency=4, worker_pool_size=None, per_item_timeout_ms=None, batch_timeout_ms=None, max_result_rows_per_item=None, max_result_bytes_per_item=None, max_batch_result_rows=None, max_batch_result_bytes=None, continue_on_error=True, max_inline_rows=5, page_size_rows=None)
- sql_execute(sql, confirm_destructive=False, max_inline_rows=None, page_size_rows=None)

Features:

Statement whitelist by category: readonly / ddl / full
Advisory permission metadata via IOTDB_SQL_DRIVER_MODE
SQL inspection returns required_permission, destructive, risk_level, approval_required, and the confirmation parameter without executing SQL
Destructive SQL confirmation policy
sql_executor_batch executes only readonly single statements. It accepts either explicit sqls=[...] or a repeated sql_template plus param_sets. Template placeholders are {{name}} for SQL literals, {{name:path}} for IoTDB paths, and {{name:identifier}} for SQL identifiers.
Batch results are per-statement ResultStore entries. The batch response returns status, result_id, row counts, a small preview, and paging metadata; use read_result_page to fetch full result pages.
Batch execution controls include a bounded thread worker pool, per-item and whole-batch wait timeouts, and per-item / whole-batch result row and byte quotas. Defaults: 4 concurrency, 60000 ms per item, 300000 ms per batch, 10000 rows and 16 MiB per item, 100000 rows and 64 MiB per batch.
Tree CQ enabled in whitelist:
- Readonly: SHOW CONTINUOUS QUERIES, SHOW CQS
- DDL: CREATE CONTINUOUS QUERY / CREATE CQ, DROP CONTINUOUS QUERY / DROP CQ
Downsampling execution path:
- ad-hoc: SELECT ... GROUP BY ([start, end), interval[, slidingStep])
- scheduled: CQ with INTO + optional RESAMPLE clause

`runtime_policy.py`

Session scoped permission controls:
- get_iotdb_session_policy()
- set_iotdb_session_policy(policy=None, preset=None, replace=False)
- reset_iotdb_session_policy(keys=None)
Presets:
- full: advisory signal for read, DDL, and DML-capable workflows
- ddl: advisory signal for read and DDL-capable workflows
- readonly: advisory signal for read-only workflows
- In strict mode only, these presets become hard execution gates
Effective policy priority:
- session overlay set by MCP tool
- dynamically read .mcp.json
- process environment
- built-in full-permission defaults

`metadata.py`

Tree dialect:
- metadata_query(query_sql)
- list_timeseries(path="root.**")
- list_devices(path="root.**")
- list_child_paths(path)
- list_child_nodes(path)
- count_timeseries(path="root.**")
- count_devices(path="root.**")
- count_nodes(path="root")
Table dialect:
- metadata_query(query_sql)
- list_tables()
- describe_table(table_name, details=True)

Metadata result sets also use ResultStore, which keeps large SHOW TIMESERIES or SHOW DEVICES responses bounded.

`explain.py`

Both dialects:
- explain_query(query_sql, analyze=False)

`database.py`

Tree dialect:
- list_databases(details=False)
- create_database(database)
- drop_database(database, confirm=False)
Table dialect:
- list_databases(details=False)
- create_database(database, if_not_exists=True)
- drop_database(database, if_exists=True, confirm=False)
- use_database(database)

`timeseries.py` (tree only)

create_timeseries_ddl(ddl_sql)
create_timeseries_batch_ddl(ddl_list, continue_on_error=True, skip_if_exists=True, max_statements=1000)
alter_timeseries_ddl(ddl_sql)
drop_timeseries_ddl(ddl_sql, confirm=False)

`ttl.py` (tree only)

ttl_command(ttl_sql, confirm_unset=False)
ttl_query(ttl_sql)

`table.py` (table only)

create_table_ddl(ddl_sql)
alter_table_ddl(ddl_sql)
drop_table_ddl(ddl_sql, confirm=False)

`udf.py`

Both dialects:
- list_udf_functions()
- prepare_udf_query(function_name, expressions, table_name=None, from_path=None, attributes=None, where_clause=None, limit=None, alias=None, align_by_device=False)
- execute_udf_query(function_name, expressions, table_name=None, from_path=None, attributes=None, where_clause=None, limit=None, alias=None, align_by_device=False, max_inline_rows=None, page_size_rows=None)
- export_udf_query(function_name, expressions, table_name=None, from_path=None, attributes=None, where_clause=None, limit=None, alias=None, align_by_device=False, format="csv", filename=None)

Features:

SHOW FUNCTIONS discovery through list_udf_functions
Conservative SQL generation for UDF calls instead of accepting raw SQL
Table dialect shape: SELECT UDF(column, "k"="v") FROM table ...
Tree dialect shape: SELECT UDF(measurement, "k"="v") FROM root.sg.d1 ...
Read-only execution only; DDL/DML keywords, semicolons, and comments are rejected in expressions and where_clause
ResultStore-backed previews for inline execution and export support for large UDF outputs

`write.py`

Tree dialect:
- write_query(write_sql, confirm_delete=False) (INSERT/DELETE)
Table dialect:
- write_query(write_sql, confirm_delete=False) (INSERT/UPDATE/DELETE)

`model.py`

Both dialects:
- model_query(model_sql)
- model_command(model_sql, confirm_destructive=False)
Tree dialect:
- prepare_model_inference_request(model_id, input_sql, output_length=96, generate_time=False)
- model_inference(inference_sql)

`json_response.py`

Shared response wrapper and parser:
- JsonParser.check_format(obj)
- JsonParser.parse(text)
- payload_response(tool, payload, message=None)
- text_payload_response(tool, text, message=None)
- csv_payload_response(tool, columns, rows, message=None)
- sql_success_response(tool, sql)

Tool Response JSON Envelope

All tools now return TextContent.text as a JSON envelope instead of plain text.

Envelope format:

{
  "version": "1.0",
  "tool": "tool_name",
  "ok": true,
  "timestamp": "2026-02-26T00:00:00+00:00",
  "payload": {},
  "message": "optional"
}

Payload conventions:

Query-like tools: payload.format="csv" with columns, preview rows, preview text, row_count, inline_row_count, inline_truncated, and ResultStore fields when persisted
Text-like tools: payload.format="text" with text
SQL success tools: payload.sql + payload.result="success"

For ResultStore-backed responses:

{
  "format": "csv",
  "columns": ["Time", "root.sg.d.s0"],
  "rows": ["0,1.0"],
  "text": "Time,root.sg.d.s0\n0,1.0",
  "row_count": 100000,
  "inline_row_count": 1,
  "inline_truncated": true,
  "result_id": "res_20260704T000000Z_0123456789abcdef",
  "owner_session_id": "ses_abc123",
  "next_cursor": "1",
  "result_store": {
    "type": "file",
    "page_tool": "read_result_page",
    "batch_page_tool": "read_result_pages",
    "owner_session_id": "ses_abc123",
    "page_size_rows": 500,
    "shard_count": 10
  }
}

Environment knobs:

TIMESEEK_RESULT_PREVIEW_ROWS default 50
TIMESEEK_RESULT_PAGE_SIZE_ROWS default 500
TIMESEEK_RESULT_MAX_PAGE_ROWS default 5000
TIMESEEK_RESULT_SHARD_ROWS default 10000
TIMESEEK_RESULT_SHARD_BYTES default 8388608
TIMESEEK_RESULT_TTL_SECONDS default 86400; set 0 to disable TTL expiry
TIMESEEK_RESULT_MAX_SESSION_RESULTS default 100; set 0 to disable
TIMESEEK_RESULT_MAX_SESSION_BYTES default 536870912; set 0 to disable
TIMESEEK_RESULT_MAX_GLOBAL_RESULTS default 1000; set 0 to disable
TIMESEEK_RESULT_MAX_GLOBAL_BYTES default 2147483648; set 0 to disable
TIMESEEK_MCP_SESSION_ID optional standalone ResultStore owner fallback
IOTDB_SQL_EXECUTOR_BATCH_MAX_STATEMENTS default 64
IOTDB_SQL_EXECUTOR_BATCH_MAX_CONCURRENCY default 16

Parser check:

Wrapper output is validated by JsonParser.check_format(...)
Serialized text is parsed again by JsonParser.parse(...) before returning
Invalid envelope shape raises ValueError

Security and Permission Model

IoTDB MCP permissions default to host-agent approval flow. The MCP server reports required permission and risk; Codex, Claude Code, or OpenCode owns user approval through its normal question/approval mechanism. This keeps MCP policy aligned with the host agent system instead of turning .mcp.json into a hard blocker.

Default mode is advisory. In advisory mode:

IOTDB_SQL_DRIVER_MODE is a prompt-layer signal, not an execution blocker.
IOTDB_ENABLE_* and *_ALLOWED_USERS are prompt-layer/session settings, not hard gates.
Destructive operations still require explicit tool confirmation flags, such as confirm_destructive=true, after the host agent has obtained approval.

Strict hard gating is available only when explicitly enabled:

TIMESEEK_MCP_PERMISSION_ENFORCEMENT=strict
# or
IOTDB_STRICT_PERMISSION_ENFORCEMENT=true

Policy can be changed at runtime without restarting the MCP server:

{
  "preset": "readonly",
  "replace": true
}

or:

{
  "policy": {
    "IOTDB_SQL_DRIVER_MODE": "full",
    "IOTDB_ENABLE_WRITE_DML": "true"
  }
}

Per-module advisory keys

database.py
- IOTDB_ENABLE_DATABASE_DDL
- IOTDB_DATABASE_DDL_ALLOWED_USERS
- IOTDB_REQUIRE_DROP_CONFIRM
timeseries.py
- IOTDB_ENABLE_TIMESERIES_DDL
- IOTDB_TIMESERIES_DDL_ALLOWED_USERS
- IOTDB_REQUIRE_TIMESERIES_DROP_CONFIRM
table.py
- IOTDB_ENABLE_TABLE_DDL
- IOTDB_TABLE_DDL_ALLOWED_USERS
- IOTDB_REQUIRE_TABLE_DROP_CONFIRM
ttl.py
- IOTDB_ENABLE_TTL_SQL
- IOTDB_TTL_ALLOWED_USERS
- IOTDB_REQUIRE_TTL_UNSET_CONFIRM
write.py
- IOTDB_ENABLE_WRITE_DML
- IOTDB_WRITE_ALLOWED_USERS
- IOTDB_REQUIRE_DELETE_CONFIRM
model.py
- IOTDB_ENABLE_MODEL_MANAGEMENT
- IOTDB_MODEL_ALLOWED_USERS
- IOTDB_REQUIRE_MODEL_DESTRUCTIVE_CONFIRM
- model_inference is registered only for tree dialect and accepts CALL INFERENCE(...) SQL.
metadata.py
- IOTDB_ENABLE_METADATA_QUERY
- IOTDB_METADATA_ALLOWED_USERS
sql_driver.py
- IOTDB_ENABLE_SQL_DRIVER
- IOTDB_SQL_DRIVER_ALLOWED_USERS
- IOTDB_SQL_DRIVER_MODE (readonly / ddl / full)
- IOTDB_SQL_DRIVER_REQUIRE_DESTRUCTIVE_CONFIRM
- IOTDB_SQL_DRIVER_EXTRA_READONLY_PREFIXES
- IOTDB_SQL_DRIVER_EXTRA_DDL_PREFIXES
- IOTDB_SQL_DRIVER_EXTRA_FULL_PREFIXES

Minimal Enablement Example

# Dialect
IOTDB_SQL_DIALECT=tree

# Keep generic driver available in full mode
IOTDB_ENABLE_SQL_DRIVER=true
IOTDB_SQL_DRIVER_MODE=full
IOTDB_SQL_DRIVER_ALLOWED_USERS=*

# Enable specialized tools
IOTDB_ENABLE_METADATA_QUERY=true
IOTDB_ENABLE_DATABASE_DDL=true
IOTDB_ENABLE_TIMESERIES_DDL=true
IOTDB_ENABLE_TTL_SQL=true
IOTDB_ENABLE_WRITE_DML=true
IOTDB_ENABLE_MODEL_MANAGEMENT=true

Notes

All tools enforce single-statement execution (; separated multi-statement is rejected).
Tool availability depends on sql_dialect (tree or table).
For production hard-block behavior, set TIMESEEK_MCP_PERMISSION_ENFORCEMENT=strict.
Keep destructive confirm flags enabled unless an external approval layer provides equivalent per-action confirmation.

IoTDB MCP Services

Registration Overview

Tool Matrix

query.py

results.py

sql_driver.py

runtime_policy.py

metadata.py

explain.py

database.py

timeseries.py (tree only)

ttl.py (tree only)

table.py (table only)

udf.py

write.py

model.py

json_response.py