IoTDB MCP Server

IoTDB MCP服务器

英语| 中文

概述

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

组件

资源

服务器不公开任何资源。

提示

服务器不提供任何提示。

工具

服务器为IoTDB树模型和表模型提供了不同的工具。您可以通过将“IOTDB_SQLDIALECT”配置设置为“树”或“表”来在它们之间进行选择。

树模型

• metadata_query

- 执行SHOW/COUNT查询以从数据库读取元数据 - 输入： - query_sql （string）：要执行的SHOW/COUNT SQL查询 - 支持的查询类型： - 显示数据库\[路径\] - 显示时间序列\[路径\] - 显示儿童路径\[路径\] - 显示儿童节点\[路径\] - 显示设备\[路径\] - 计数时间序列\[路径\] - 计数节点\[路径\] - 计数设备\[路径\] - 返回：查询结果为对象数组

• select_query

- 执行SELECT查询以从数据库中读取数据 - 输入： - query_sql （string）：要执行的SELECT SQL查询（使用TREE方言，时间使用ISO 8601格式，例如2017-11-01T00:08:00.000） - 支持的功能： - 求和、计数、最大值、最小值、平均值、方差、最大时间、最小时间等。 - 返回：查询结果为对象数组

• export_query

- 执行查询并将结果导出到CSV或Excel文件 - 输入： - query_sql （string）：要执行的SQL查询（使用TREE方言） - format （字符串）：导出格式，“csv”或“excel”（默认：“csv”） - filename （string）：导出文件的可选文件名。如果没有提供，将生成一个唯一的文件名。 - 返回：有关导出文件的信息和数据预览（最多10行）

表格模型

查询工具

• read_query

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

架构工具

• list_tables

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

• describe_table

- 查看特定表的架构信息 - 输入： - table_name （string）：要描述的表的名称 - 返回：包含名称和类型的列定义数组

• export_table_query

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

配置选项

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

性能优化

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

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

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

macOS

地点： ~/Library/Application Support/Claude/claude_desktop_config.json

视窗

地点： %APPDATA%/Claude/claude_desktop_config.json

您可能需要在命令字段中输入uv可执行文件的完整路径。你可以通过跑步来获得这个 which uv 在MacOS/Linux或 where uv 在Windows上。

Claude桌面配置示例

将以下配置添加到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 在项目根目录中：

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

# Run container
docker run -e IOTDB_HOST= -e IOTDB_PORT= -e IOTDB_USER= -e IOTDB_PASSWORD= iotdb-mcp-server