物联网数据库MCP服务器

Name: 物联网数据库MCP服务器
Author: apache

作者：apache28 星标更新：2025-07-16

安装使用来源：spider==github.com

项目介绍

IoTDB MCP Server

English | 中文

概述

这是一个通过IoTDB提供数据库交互和商业智能能力的Model Context Protocol (MCP)服务器实现。该服务器支持使用不同的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 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=<您的IoTDB主机> -e IOTDB_PORT=<您的IoTDB端口> -e IOTDB_USER=<您的IoTDB用户> -e IOTDB_PASSWORD=<您的IoTDB密码> iotdb-mcp-server