IoTDB MCP Server

IoTDB MCP 服务

English | 中文

概述

一种模型上下文协议（MCP）服务实现，通过 IoTDB 提供数据库交互和商业智能功能。此服务支持运行 SQL 查询，并使用不同的 SQL 方言（树模型和表模型）与 IoTDB 交互。

组件

资源

此服务不提供任何资源。

提示词

此服务不提供任何提示词。

权限模型

IoTDB MCP 权限默认仅供参考。服务会报告 SQL 操作所需的权限、风险等级和确认参数，而用户审批由宿主 Agent 系统负责。当工具可用时，请在执行 DDL/DML 或具有破坏性的 SQL 前使用 inspect_sql_permission。

长期运行的托管 Agent 可通过环境变量（如 IOTDB_SQL_DRIVER_MODE=full 和 TIMESEEK_MCP_PERMISSION_ENFORCEMENT=advisory）提供默认的完整权限。只有在 MCP 服务本身应硬性阻止不允许的操作时，才设置 TIMESEEK_MCP_PERMISSION_ENFORCEMENT=strict。

会话策略变更受启动时冻结的部署策略约束（进程环境 > MCP 配置 > 默认值）。收紧策略会立即生效；在此上限范围内放宽策略，默认需要管理员通过带外方式批准。IOTDB_SESSION_POLICY_APPROVAL_MODE=allow 可明确允许在上限范围内无需批准即可放宽策略。这两项设置都不会允许工具更改强制执行开关、SQL 分类前缀或部署上限。重置和替换也遵循相同规则。有关配置、审批命令和所需宿主隔离，请参阅会话策略管理。

工具

此服务为 IoTDB 树模型和表模型提供不同的工具。你可以将“IOTDB_SQL_DIALECT”配置设为“tree”或“table”，以进行选择。

方言特定的标识符语义：

• 树方言：
  • FROM 目标使用显式的 root... 路径。
  • 投影表达式通常应使用测量名称，而不是完整的 root... 路径。
  • IOTDB_DATABASE 仅作为连接/会话提示；树 SQL 仍需要显式的根路径。
• 表方言：
  • FROM 目标使用当前数据库中的表名。
  • 投影表达式使用列名。

树模型

• metadata_query
  • 执行 SHOW/COUNT 查询以读取数据库中的元数据
  • 输入：
    • query_sql (string)：要执行的 SHOW/COUNT SQL 查询
  • 支持的查询类型：
    • 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]
  • 返回：以对象数组形式返回查询结果
• select_query
  • 执行 SELECT 查询以读取数据库中的数据
  • 输入：
    • query_sql (string)：要执行的 SELECT SQL 查询（使用 TREE 方言，时间采用 ISO 8601 格式，例如 2017-11-01T00:08:00.000）
  • 支持的函数：
    • SUM、COUNT、MAX_VALUE、MIN_VALUE、AVG、VARIANCE、MAX_TIME、MIN_TIME 等
  • 返回：以对象数组形式返回查询结果
• sql_executor_batch
  • 并行执行多个只读 SQL 语句，并将每个结果存储在 ResultStore 中
  • 输入：
    • sqls（数组）：明确指定的单条 SQL 语句，或
    • sql_template + param_sets：带参数对象的重复 SQL 模板
    • max_concurrency（整数）：并发语句数上限，默认为 4
    • worker_pool_size（整数）：线程工作池大小，默认值跟随并发数，且不超过 IOTDB_SQL_EXECUTOR_BATCH_MAX_WORKER_POOL_SIZE（默认值为 16）
    • per_item_timeout_ms（整数）：每条语句的等待超时，默认为 60000
    • batch_timeout_ms（整数）：整个批次的等待超时，默认为 300000
    • max_result_rows_per_item / max_result_bytes_per_item：每条语句的结果配额，默认分别为 10000 行和 16 MiB
    • max_batch_result_rows / max_batch_result_bytes：整个批次的结果配额，默认分别为 100000 行和 64 MiB
  • 模板占位符：
    • {{name}} 用于 SQL 字面值，{{name:path}} 用于 IoTDB 路径，{{name:identifier}} 用于 SQL 标识符
  • 返回：批次摘要，以及每条语句的 result_id、行数、预览行和分页元数据
• read_result_pages
  • 在一次 MCP 调用中读取多个 ResultStore 页面
  • 输入：
    • pages（数组）：页面请求对象，包含 result_id，以及可选的 cursor、offset、limit 和 owner_session_id
    • default_limit（整数）：未提供 limit 的项目所使用的默认页面大小
    • max_pages / max_total_rows：单次调用的配额，默认分别为 32 页和 10000 行
    • continue_on_error（布尔值）：返回每项错误而不中止，默认为 true
  • 返回：批次页面摘要，以及每页的行、游标和错误
• export_query
  • 执行查询并将结果导出为 CSV 或 Excel 文件
  • 输入：
    • query_sql（string）：要执行的 SQL 查询（使用 TREE 方言）
    • format（string）：导出格式，可以是 "csv" 或 "excel"（默认值："csv"）
    • filename（string）：导出文件的可选文件名。如果未提供，将生成唯一文件名。
  • 返回：导出文件的信息和数据预览（最多 10 行）
• model_inference
  • 执行 AINode CALL INFERENCE(...) SQL 并返回结果集
  • 输入：
    • inference_sql（string）：以 CALL INFERENCE 开头的单条 Tree 方言 SQL 语句
  • 执行前会验证模型 ID、加引号的输入 SELECT SQL、显式的非通配符列，以及受支持的参数（generateTime、outputLength）
  • 权限元数据：模型管理通过 MCP 建议性策略层进行报告。在严格模式下，会强制执行 IOTDB_ENABLE_MODEL_MANAGEMENT=true 和 IOTDB_MODEL_ALLOWED_USERS。
• prepare_model_inference_request
  • 根据结构化字段构建并验证 AINode CALL INFERENCE(...) SQL
  • 输入：
    • model_id（string）：已注册的 AINode 模型 ID
    • input_sql（string）：用作模型输入的有界 Tree 方言 SELECT 查询
    • output_length（int）：预测输出长度（默认值：96）
    • generate_time（bool）：是否请求 Time 列（默认值：false）

UDF 工具

• list_udf_functions
  • 对选定的 IoTDB 目标执行 SHOW FUNCTIONS。
• prepare_udf_query
  • 根据结构化输入构建只读 UDF SELECT 查询。
  • 树形形式：SELECT UDF(measurement, "k"="v") FROM root.sg.d1 ...
  • 表格形式：SELECT UDF(column, "k"="v") FROM table ...
• execute_udf_query
  • 执行经过验证的 UDF 查询，并返回由 ResultStore 支持的预览。
• export_udf_query
  • 执行经过验证的 UDF 查询，并将结果集导出为 CSV 或 Excel。

UDF 工具会拒绝表达式和筛选子句中的分号、SQL 注释以及 DDL/DML 关键字。 这些工具适用于只读 UDF 调用，例如数据质量检查、分析、修复规划和异常评分。

表模型

查询工具

• read_query
  • 执行 SELECT 查询以从数据库读取数据
  • 输入：
    • query_sql（字符串）：要执行的 SELECT SQL 查询（使用 TABLE 方言，时间采用 ISO 8601 格式，例如 2017-11-01T00:08:00.000）
  • 返回：以对象数组形式返回查询结果

架构工具

• list_tables

  • 获取数据库中的所有表
  • 无需输入
  • 返回：表名数组

• describe_table

  • 查看特定表的架构信息
  • 输入：
    • table_name（字符串）：要查看的表名
  • 返回：包含列名和类型的列定义数组

• export_table_query

  • 执行查询并将结果导出为 CSV 或 Excel 文件
  • 输入：
    • query_sql（字符串）：要执行的 SQL 查询（使用 TABLE 方言）
    • format（字符串）：导出格式，可以是 "csv" 或 "excel"（默认值："csv"）
    • filename（字符串）：导出文件的可选文件名。如果未提供，将生成唯一的文件名。
  • 返回：有关导出文件的信息以及数据预览（最多 10 行）

配置选项

IoTDB MCP Server 支持以下配置选项，可通过环境变量或命令行参数设置：

选项	环境变量	默认值	说明
--host	IOTDB_HOST	127.0.0.1	IoTDB 主机地址
--port	IOTDB_PORT	6667	IoTDB 端口
--user	IOTDB_USER	root	IoTDB 用户名
--password	IOTDB_PASSWORD	empty	IoTDB 密码
--database	IOTDB_DATABASE	test	表模式：当前数据库名称。树模式：可选的会话/根范围提示；查询仍使用显式的 root... 路径。
--sql-dialect	IOTDB_SQL_DIALECT	table	SQL 方言：tree 或 table
--export-path	IOTDB_EXPORT_PATH	/tmp	查询结果的导出路径

目标注册表中仅包含已成功登录的连接。调用 prepare_iotdb_target 并提供非机密字段，然后将用户明确提供的凭据传递给 connect_iotdb_target，进行一次身份验证尝试。如果没有凭据，请询问用户；切勿尝试空密码或默认密码。用户明确提供的空密码仍是有效输入。

登录成功后，目标会以原子方式发布，并记录其对应的 last_known_good_credential。任何连接层故障都会消耗候选项或逐出已发布的目标。重试需要新建候选项，并且必须在用户明确指示后设置 user_confirmed_retry=true。公开的目标响应会隐藏当前密码和上次已知有效密码。

配置 TIMESEEK_IOTDB_TARGETS_FILE 后，默认会持久化成功建立的连接。本地 Java CLI 可通过 iotdb-target-cli 重用该目标：

iotdb-target-cli --target-id cloud \
  --cli /opt/iotdb/sbin/start-cli.sh -- -e "SHOW VERSION"

该包装器会在每次调用时重新加载已验证的目标，并提供其主机、端口、方言、用户名和上次已知有效密码。由于 Java CLI 不支持 -db 选项，因此不会将 -db 传递给 start-cli.sh；要选择表数据库，请使用 SQL USE <database>。对于支持 -db 的 import-data.sh 和 import-data.bat，系统会自动注入表目标的数据库。已验证的空密码会通过省略 -pw 表示，命令预览则会隐藏非空密码。直接调用 start-cli.sh 不会读取目标注册表。

性能优化

IoTDB MCP Server 包含以下性能优化功能：

1. 会话池管理：使用经过优化的会话池配置，最多支持 100 个并发会话
2. 优化的提取大小：查询的提取大小设置为 1024
3. 连接重试：针对连接故障配置了自动重试机制
4. 超时管理：会话等待超时设置为 5000 毫秒，以提高可靠性
5. 导出功能：支持将查询结果导出为 CSV 或 Excel 格式

前提条件

• Python 环境
• uv 包管理器
• IoTDB 安装
• MCP 服务依赖项

开发

# Clone the repository
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server

# Create virtual environment
uv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
uv sync

Claude Desktop 集成

在 Claude Desktop 的配置文件中配置 MCP 服务：

macOS

位置：~/Library/Application Support/Claude/claude_desktop_config.json

Windows

位置：%APPDATA%/Claude/claude_desktop_config.json

你可能需要在 command 字段中填写 uv 可执行文件的完整路径。在 MacOS/Linux 上运行 which uv，或在 Windows 上运行 where uv，即可获取该路径。

Claude Desktop 配置示例

将以下配置添加到 Claude Desktop 的配置文件中：

{
  "mcpServers": {
    "iotdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
      ],
      "env": {
        "IOTDB_HOST": "127.0.0.1",
        "IOTDB_PORT": "6667",
        "IOTDB_USER": "root",
        "IOTDB_PASSWORD": "",
        "IOTDB_DATABASE": "test",
        "IOTDB_SQL_DIALECT": "table",
        "IOTDB_EXPORT_PATH": "/path/to/export/folder"
      }
    }
  }
}

注意：请确保将 --directory 参数的路径替换为你实际克隆的仓库路径。

错误处理和日志记录

IoTDB MCP Server 提供全面的错误处理和日志记录功能：

1. 日志级别：日志级别设置为 INFO，可在控制台查看服务状态
2. 异常处理：所有数据库操作均包含异常处理，确保出现错误时能够妥善处理并提供有意义的错误消息
3. 会话管理：自动关闭已使用的会话，以防止资源泄漏
4. 参数验证：对用户输入的 SQL 查询进行基本验证，确保只执行允许的查询类型

Docker 支持

你可以使用项目根目录中的 Dockerfile 为 IoTDB MCP Server 构建容器镜像：

# Build Docker image
docker build -t iotdb-mcp-server .

# Run container
docker run -e IOTDB_HOST=<your-iotdb-host> -e IOTDB_PORT=<your-iotdb-port> -e IOTDB_USER=<your-iotdb-user> -e IOTDB_PASSWORD=<your-iotdb-password> iotdb-mcp-server