IoTDB MCP 让你用最轻松的方法，运用大模型的深度时序数据管理能力！
近些年 AI 变得越发普及，大语言模型（LLM）已经成为我们生活中不可或缺的助手。而在时序数据管理领域，大语言模型也有望成为加速数据查询与分析的重要工具，如何让大语言模型与时序数据库深度交互，用更小的理解成本调用大语言模型的强大能力，成为行业关注热点。
Model Context Protocol（MCP）的出现，让我们看到了 AI 技术与时序数据库融合的全新可能，并基于此实现了 Apache IoTDB MCP Server 功能。这一功能让过去“先向大模型提出问题，由其输出 IoTDB 的 SQL 语句，再手动执行 SQL 语句获取结果”的使用过程，变为“大模型直接与 IoTDB 交互获取所需数据”，极大简化了数据查询的流程，为时序数据管理带来了全新的解决方案。
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 开源。
(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
sourcevenv/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：
createdatabase 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:00 AND time < 2025-03-20T00:00:00")
场景2：数据探索
用户输入：“数据库中有哪些表？”
→ 大模型调用：
list_tables()
场景3：结构分析
用户输入：“描述 battery_data 表的结构”
→ 大模型执行：
describe_table("battery_data")
04 结语
MCP 技术的出现，为大语言模型的应用开辟了新的天地，通过 MCP 协议，我们正在构建一个大模型与物理世界无缝交互的新范式。Apache IoTDB MCP Server 作为 MCP 技术的成功实践，为时序数据处理提供了标准化的大模型接入方案。随着生态的完善，MCP 有望成为连接 AI 与 IoT 的关键基础设施。
期待利用 Apache IoTDB MCP Server，更多企业能够加速时序数据智能化管理，实现大语言模型在时序数据管理领域的深度使用。欢迎各位朋友下载并试用！
