IoTDB MCP 服务器

English | 中文

概述

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

组件

资源

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

提示

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

工具

该服务器为 IoTDB 树模型和表模型提供了不同的工具。您可以通过将 "IOTDB_SQL_DIALECT" 配置设置为 "tree" 或 "table" 来选择它们。

树模型

• metadata_query
  • 执行 SHOW/COUNT 查询以从数据库中读取元数据
  • 输入：
    • query_sql (字符串): 要执行的 SHOW/COUNT SQL 查询
  • 支持的查询类型：
    • SHOW DATABASES [路径]
    • SHOW TIMESERIES [路径]
    • SHOW CHILD PATHS [路径]
    • SHOW CHILD NODES [路径]
    • SHOW DEVICES [路径]
    • COUNT TIMESERIES [路径]
    • COUNT NODES [路径]
    • COUNT DEVICES [路径]
  • 返回：查询结果作为对象数组
• select_query
  • 执行 SELECT 查询以从数据库中读取数据
  • 输入：
    • query_sql (字符串): 要执行的 SELECT SQL 查询（使用 TREE 方言，时间使用 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 查询（使用 TREE 方言）
    • format (字符串): 导出格式，可以是 "csv" 或 "excel"（默认： "csv"）
    • filename (字符串): 导出文件的可选文件名。如果未提供，将生成一个唯一的文件名。
  • 返回：有关导出文件的信息和数据预览（最多 10 行）

表模型

查询工具

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

性能优化

IoTDB MCP 服务器包含以下性能优化功能：

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 集成

在 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 服务器包含全面的错误处理和日志记录功能：

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

Docker 支持

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

# 构建 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