不想学 SQL?IoTDB MCP:让时序数据库“听懂人话”

IoTDB MCP 让你用最轻松的方法,运用大模型的深度时序数据管理能力!

近些年 AI 变得越发普及,大语言模型(LLM)已经成为我们生活中不可或缺的助手。而在时序数据管理领域,大语言模型也有望成为加速数据查询与分析的重要工具,如何让大语言模型与时序数据库深度交互,用更小的理解成本调用大语言模型的强大能力,成为行业关注热点。

Model Context Protocol(MCP)的出现,让我们看到了 AI 技术与时序数据库融合的全新可能,并基于此实现了 Apache IoTDB MCP Server 功能。这一功能让过去“先向大模型提出问题,由其输出 IoTDB 的 SQL 语句,再手动执行 SQL 语句获取结果”的使用过程,变为“大模型直接与 IoTDB 交互获取所需数据”,极大简化了数据查询的流程,为时序数据管理带来了全新的解决方案。

01

MCP:让大模型“看得懂”外部世界

02

Apache IoTDB MCP Server:让大模型会用 IoTDB

03

Apache IoTDB MCP Server:典型使用场景

04

结语

01 MCP:让大模型“看得懂”外部世界

(1) MCP 是什么?

Model Context Protocol(MCP)是由 Anthropic 提出的标准化协议,旨在为大语言模型提供与外部软件和系统交互的能力。你可以想象一个场景:你带着国内的充电器出国,发现无法充电,需要一个转换插头。MCP 就是 AI 的“转换插头”,让 AI 能够连接和使用各种外部工具和数据源,进而拓展 AI 能力的应用场景。

具体来说,MCP 的工作原理是这样的:开发者使用 Python 等编程语言实现特定的功能函数,并用自然语言详细描述这些函数的功能以及各个参数的含义。当大模型接收到一个任务时,它会根据自然语言描述提取出函数的参数,调用相应的函数,并将结果返回给用户。这一过程就像是给大模型配备了一双“眼睛”,让它能够“看到”并操作外部世界的各种软件和系统。

(2) 为什么需要 MCP?

在没有 MCP 的情况下,大模型的功能主要局限于文本处理。例如,如果你想要查询数据库中的某些数据,你需要手动编写 SQL 查询语句,或者通过其他工具来完成。

但有了 MCP,你只需要用自然语言描述你的需求,比如“查询风机今日的运行情况”,大模型就能自动调用相应的数据库查询函数,完成任务并返回结果。这不仅大大提高了效率,还降低了对用户的技术要求,让普通用户也能轻松利用大模型的强大能力。

(3) MCP 的核心价值

  • 实时性:突破 LLM 训练数据的时间限制,支持查询动态更新的数据库内容。

  • 统一性:标准化工具调用格式,替代传统分散的 Function Call 实现方式。

  • 安全性:通过隔离敏感数据访问权限,仅由 MCP Server 管理凭证,避免直接暴露给 LLM。

02 Apache IoTDB MCP Server:让大模型会用 IoTDB

(1) IoTDB MCP Server 是什么?

Apache IoTDB MCP Server 是一个基于 MCP 协议的服务器实现,它通过 IoTDB 提供数据库交互和商业智能功能。Apache IoTDB 是专门为物联网(IoT)数据设计的数据库,能够高效地存储和处理海量的时序数据。而 IoTDB MCP Server 则为大模型与 IoTDB 数据库之间搭建了一座桥梁,让大模型能够轻松地查询 IoTDB 中的海量时序数据。

目前,该功能已在 GitHub 开源:https://github.com/apache/iotdb-mcp-server

(2) IoTDB MCP Server 的核心功能

1. 查询工具(Query Tools)

  • read_query:执行 SELECT 查询语句,从数据库中读取数据。用户只需要提供一个 SELECT SQL 查询语句作为输入,read_query 函数就会返回查询结果,结果以对象数组的形式呈现。例如,如果你想要查询某个设备在过去一周内的温度数据,你可以用自然语言描述这个需求,大模型就会调用 read_query 函数,传入相应的 SQL 查询语句,然后返回温度数据。

2. 元数据工具(Schema Tools)

  • list_tables:获取数据库中所有表的列表。这个函数不需要任何输入,直接返回一个包含所有表名的数组。当你不确定数据库中有哪些表时,这个功能非常有用。

  • describe_table:查看特定表的元数据信息。用户需要提供表名作为输入,函数会返回该表的列定义,包括列名和数据类型。例如,你可以用自然语言询问某个表的结构,大模型就会调用 describe_table 函数,返回表的详细信息。

(3) 如何使用 IoTDB MCP Server?

使用 IoTDB MCP Server 需要满足一些前提条件:

  • 安装 Python,并使用 uv 包管理器(pip install uv)

  • 安装并运行 IoTDB 数据库实例(可下载 2.0.1-beta 版本)

  • 安装 IoTDB MCP Server 的依赖项

接下来,按照以下步骤进行操作:

1. 克隆仓库

打开终端,运行以下命令克隆 IoTDB MCP Server 的代码仓库:

git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb_mcp_server

2. 创建虚拟环境

使用 uv 创建虚拟环境,并激活它:

uv venv
source venv/bin/activate  # 或在 Windows 上使用 venv\Scripts\activate

3. 安装依赖

在虚拟环境中,运行以下命令安装开发依赖:

uv sync

4. 配置集成(以 Claude Desktop 为例)

根据你的操作系统,找到 Claude Desktop 的配置文件:

  • 在 MacOS 上,位置为 ~/Library/Application Support/Claude/claude_desktop_config.json

  • 在 Windows 上,位置为 %APPDATA%/Claude/claude_desktop_config.json

在配置文件中,添加以下内容,确保将 YOUR_REPO_PATH 替换为你的仓库路径,env 配置为实际的 IoTDB 实例信息:

{
  "mcpServers": {
    "iotdb": {
      "command": "uv",
      "args": [
        "--directory",
        "YOUR_REPO_PATH/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"
      }
    }
  }
}

如果你需要找到 uv 的完整路径,可以在 MacOS/Linux 上运行 which uv,在 Windows 上运行 where uv。

5. 打开 Claude Desktop,开始体验

正式使用前请提前准备好数据,目前 Apache IoTDB MCP Server 仅支持表模型,也可以直接使用下方的 SQL 快速录入测试数据,首先使用 start-cli.sh/bat -sql_dialect table 进入 IoTDB CLI:

create database test;
use test;

CREATE TABLE battery_data (
    time TIMESTAMP TIME comment '时间', 
    station_id STRING TAG comment '站址ID',
    dc_voltage FLOAT FIELD comment '直流电压(V)',
    load_current FLOAT FIELD comment '负载电流(A)',
    battery_current FLOAT FIELD comment '电池组电流(A)',
    float_voltage_set FLOAT FIELD comment '浮充电压设定值(V)',
    equalize_voltage_set FLOAT FIELD comment '均充电压设定值(V)',
    rectifier_current FLOAT FIELD comment '整流模块电流和(A)'
) comment '电池数据'

insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742313600000,'b0001',50.88,69.36,0.0,50.9,51.1,82.48);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742313720000,'b0001',50.88,67.05,0.0,50.9,51.1,81.12);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742313840000,'b0001',50.88,67.37,0.0,50.9,51.1,81.24);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742313960000,'b0001',50.88,68.72,0.0,50.9,51.1,82.49);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314080000,'b0001',50.88,67.27,0.0,50.9,51.1,80.24);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314200000,'b0001',50.89,66.89,0.0,50.9,51.1,79.99);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314380000,'b0001',50.88,69.53,0.0,50.9,51.1,83.23);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314500000,'b0001',50.88,68.23,0.0,50.9,51.1,79.48);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314620000,'b0001',50.88,69.76,0.0,50.9,51.1,83.36);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314740000,'b0001',50.88,67.46,0.0,50.9,51.1,81.99);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314860000,'b0001',50.88,67.39,0.0,50.9,51.1,80.98);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742314980000,'b0001',50.88,65.51,0.0,50.9,51.1,78.73);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315100000,'b0001',50.88,66.11,0.0,50.9,51.1,80.49);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315220000,'b0001',50.88,68.6,0.0,50.9,51.1,81.87);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315340000,'b0001',50.88,66.42,0.0,50.9,51.1,78.23);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315460000,'b0001',50.88,67.16,0.0,50.9,51.1,78.49);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315580000,'b0001',50.88,66.6,0.0,50.9,51.1,78.36);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315700000,'b0001',50.88,67.53,0.0,50.9,51.1,79.98);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315820000,'b0001',50.88,66.69,0.0,50.9,51.1,79.73);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742315940000,'b0001',50.88,66.88,0.0,50.9,51.1,80.87);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316060000,'b0001',50.88,67.0,0.0,50.9,51.1,79.73);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316180000,'b0001',50.88,65.61,0.0,50.9,51.1,79.86);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316300000,'b0001',50.89,61.51,0.0,50.9,51.1,73.98);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316420000,'b0001',50.89,62.38,0.0,50.9,51.1,75.86);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316540000,'b0001',50.89,60.35,0.0,50.9,51.1,73.23);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316720000,'b0001',50.89,60.22,0.0,50.9,51.1,72.61);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316840000,'b0001',50.89,60.88,0.0,50.9,51.1,73.98);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742316960000,'b0001',50.89,59.95,0.0,50.9,51.1,72.61);
insert into battery_data(time,station_id,dc_voltage,load_current,battery_current,float_voltage_set,equalize_voltage_set,rectifier_current) values(1742317080000,'b0001',50.89,61.09,0.0,50.9,51.1,74.11);

03 Apache IoTDB MCP Server:典型使用场景

场景1:自然语言查询数据库

用户输入:“查询 2025 年 3 月 19 日所有基站的整流模块电流平均值”

→ 大模型转换为:

read_query("SELECT AVG(rectifier_current) as average_rectifier_current FROM battery_data WHERE time >= 2025-03-19T00:00:0

IoTDB MCP文章图1-20250403.png

场景2:数据探索

用户输入:“数据库中有哪些表?”

→ 大模型调用:

list_tables()

IoTDB MCP文章图2-20250403.png

场景3:结构分析

用户输入:“描述 battery_data 表的结构”

→ 大模型执行:

describe_table("battery_data")

IoTDB MCP文章图3-20250403.png

04 结语

MCP 技术的出现,为大语言模型的应用开辟了新的天地,通过 MCP 协议,我们正在构建一个大模型与物理世界无缝交互的新范式。Apache IoTDB MCP Server 作为 MCP 技术的成功实践,为时序数据处理提供了标准化的大模型接入方案。随着生态的完善,MCP 有望成为连接 AI 与 IoT 的关键基础设施。

期待利用 Apache IoTDB MCP Server,更多企业能够加速时序数据智能化管理,实现大语言模型在时序数据管理领域的深度使用。欢迎各位朋友下载并试用!

更多内容推荐:

下载时序数据库 IoTDB 开源版

了解如何使用 时序数据库 IoTDB AI 能力