IoTDB MCP Server

概述

IoTDB MCP Server 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器实现，通过 IoTDB 提供数据库交互和商业智能能力。该服务器支持执行 SQL 查询，并可以通过不同的 SQL 方言（树模型和表模型）与 IoTDB 进行交互。

组件

资源

此服务器不暴露任何资源。

提示

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

工具

服务器为 IoTDB 的树模型（Tree Model）和表模型（Table Model）提供了不同的工具。您可以通过设置 “IOTDB_SQL_DIALECT” 配置为 “tree” 或 “table” 来选择使用哪种模型。

树模型 (Tree Model)

metadata_query
- 执行 SHOW/COUNT 查询以从数据库读取元数据
- 输入:
  - query_sql (字符串): 要执行的 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 (字符串): 要执行的 SELECT SQL 查询（使用树模型方言，时间使用 ISO 8601 格式，例如 2017-11-01T00:08:00.000）
- 支持的函数:
  - SUM, COUNT, MAX_VALUE, MIN_VALUE, AVG, VARIANCE, MAX_TIME, MIN_TIME 等
- 返回: 查询结果作为对象数组
export_query
- 执行查询并将结果导出为 CSV 或 Excel 文件
- 输入:
  - query_sql (字符串): 要执行的 SQL 查询（使用树模型方言）
  - format (字符串): 导出格式，可以是 “csv” 或 “excel”（默认: “csv”）
  - filename (字符串): 导出文件的文件名（可选，如果未提供，将生成唯一文件名）
- 返回: 有关导出文件的信息和数据预览（最多 10 行）

表模型 (Table Model)

read_query
- 执行 SELECT 查询以从数据库读取数据
- 输入:
  - query_sql (字符串): 要执行的 SELECT SQL 查询（使用表模型方言，时间使用 ISO 8601 格式，例如 2017-11-01T00:08:00.000）
- 返回: 查询结果作为对象数组
list_tables
- 获取数据库中所有表的列表
- 无需输入参数
- 返回: 表名数组
describe_table
- 查看特定表的模式信息
- 输入:
  - table_name (字符串): 要描述的表名
- 返回: 包含列名和类型的列定义数组
export_table_query
- 执行查询并将结果导出为 CSV 或 Excel 文件
- 输入:
  - query_sql (字符串): 要执行的 SQL 查询（使用表模型方言）
  - 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	root	IoTDB 密码
--database	IOTDB_DATABASE	test	IoTDB 数据库名称
--sql-dialect	IOTDB_SQL_DIALECT	table	SQL 方言: tree 或 table
--export-path	IOTDB_EXPORT_PATH	/tmp	查询结果导出路径

性能优化

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

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

前提条件

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

开发

# 克隆仓库
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server

# 创建虚拟环境
uv venv
source venv/bin/activate  # 或在 Windows 上使用 `venv\Scripts\activate`

# 安装开发依赖
uv sync

在 Claude Desktop 中配置

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

macOS

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

Windows

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

你可能需要在命令字段中放入 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": "root",
        "IOTDB_DATABASE": "test",
        "IOTDB_SQL_DIALECT": "table",
        "IOTDB_EXPORT_PATH": "/path/to/export/folder"
      }
    }
  }
}

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

错误处理与日志

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

日志级别：日志记录级别设置为 INFO，可以在控制台查看服务器的运行状态
异常处理：所有的数据库操作都包含了异常处理，确保在出现错误时能够优雅地处理并返回有意义的错误消息
会话管理：自动关闭已使用的会话，防止资源泄露
参数验证：对用户输入的 SQL 查询进行基本验证，确保只有允许的查询类型被执行

Docker 支持

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

# 构建 Docker 镜像
docker build -t iotdb-mcp-server .

# 运行容器
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