English | 中文

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

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

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

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

• 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 行）

• 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 支持以下配置选项，可以通过环境变量或命令行参数进行设置：

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

1. 会话池管理：使用优化的会话池配置，可支持最多 100 个并发会话
2. 优化的获取大小：对于查询，设置了 1024 的获取大小
3. 连接重试：配置了连接失败时的自动重试机制
4. 超时管理：会话等待超时设置为 5000 毫秒，提高可靠性
5. 导出功能：支持将查询结果导出为 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 的配置文件中设置 MCP 服务器：

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

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

你可能需要在命令字段中放入 uv 可执行文件的完整路径。你可以通过在 macOS/Linux 上运行 which uv 或在 Windows 上运行 where uv 来获取这个路径。

将以下配置添加到 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 包含全面的错误处理和日志记录功能：

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

您可以使用项目根目录下的 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