关键词

物联网集成智能家居自动化工业控制LLM代理工具MQTT桥接

使用说明

项目简介

'mqtt-mcp' 是一个轻量级的Model Context Protocol (MCP) 服务器，旨在安全、标准化地连接大型语言模型 (LLM) 智能体与 MQTT 设备。它允许LLM智能体监控实时传感器数据、执行设备操作和编排复杂的自动化任务，特别适用于楼宇自动化 (BAS)、工业控制系统 (ICS) 和智能家居等场景。通过将MQTT操作抽象为MCP的资源和工具，它极大地简化了LLM与物联网设备的集成过程。

主要功能点

  • MQTT消息接收: LLM智能体可以请求从指定MQTT主题接收消息，支持设置超时，从而获取实时的传感器数据或设备状态更新。
  • MQTT消息发布: LLM智能体可以向指定MQTT主题发布消息，实现远程设备控制、触发自动化流程或发送指令。
  • 上下文管理: 利用MCP的资源(Resources)、工具(Tools)和Prompt模板，'mqtt-mcp' 以标准化方式向LLM提供MQTT相关的上下文信息和操作能力，使得LLM能够理解并操作物联网环境。
  • 会话与认证: 服务器支持会话管理和可选的AuthKit认证提供者，确保LLM与MQTT设备之间交互的安全性和可控性。
  • 多传输协议: 默认通过Streamable HTTP端点提供服务，方便各种MCP客户端进行连接。
  • 自动化任务编排: 结合LLM的推理能力，可以通过MQTT工具实现复杂的自动化任务，例如根据传感器数据自动调整空调，或在特定事件发生时触发警报。

安装步骤

推荐使用 'uv' 或 'pip' 将 'mqtt-mcp' 安装到您的Python项目中。

# 使用 uv (推荐)
uv add mqtt-mcp

# 或者使用 pip
pip install mqtt-mcp

服务器配置

MCP客户端需要以下JSON配置信息来连接到 'mqtt-mcp' 服务器。服务器默认将运行在 'http://127.0.0.1:8000/mcp/'。这些配置应在您的MCP客户端应用中进行设置，而非直接在 'mqtt-mcp' 服务器代码中修改。

{
  "server_label": "MQTT上下文服务器",
  "server_url": "http://127.0.0.1:8000/mcp/",
  "command": "mqtt-mcp",
  "args": ["run"],
  "allowed_tools": ["receive_message", "publish_message"],
  "require_approval": "never"
}

配置参数注释：

  • 'server_label': 在MCP客户端界面中显示的服务器名称，例如 "MQTT上下文服务器"。
  • 'server_url': MCP服务器监听的HTTP端点地址，通常是 'http://127.0.0.1:8000/mcp/'。
  • 'command': 启动 'mqtt-mcp' 服务器的可执行命令，通常是 'mqtt-mcp'。
  • 'args': 传递给 'command' 的参数列表，例如 '["run"]' 命令用于启动服务器。
  • 'allowed_tools': 一个字符串数组，列出允许LLM智能体通过此MCP服务器调用的工具名称。在此项目中，主要包括 'receive_message'（接收MQTT消息）和 'publish_message'（发布MQTT消息）。
  • 'require_approval': 控制LLM智能体调用工具时是否需要用户批准。可选值为 '"never"'（从不批准）、'"always"'（总是批准）或 '"first"'（首次调用需要批准）。

基本使用方法

1. 启动MQTT MCP服务器

在您的终端中运行以下命令以启动 'mqtt-mcp' 服务器：

mqtt-mcp

服务器默认将在 'http://127.0.0.1:8000/mcp/' 监听传入的MCP请求。

2. 配置MQTT连接（可选）

您可以选择通过环境变量或在工作目录下的 '.env' 文件中配置默认的MQTT代理连接信息，以便服务器在操作时使用：

使用环境变量：

export MQTT_MCP_MQTT__HOST=您的MQTT主机IP
export MQTT_MCP_MQTT__PORT=您的MQTT端口
export MQTT_MCP_MQTT__USERNAME=您的MQTT用户名 # 如果需要认证
export MQTT_MCP_MQTT__PASSWORD=您的MQTT密码 # 如果需要认证

使用 '.env' 文件：

在项目根目录创建或编辑 '.env' 文件，添加以下内容：

# .env
mqtt_mcp_mqtt__host=您的MQTT主机IP
mqtt_mcp_mqtt__port=您的MQTT端口
mqtt_mcp_mqtt__username=您的MQTT用户名
mqtt_mcp_mqtt__password=您的MQTT密码

3. 连接MCP Inspector进行验证

为了确认服务器已成功启动并探索其提供的资源和工具，您可以安装并运行 MCP Inspector 工具。连接到服务器地址 'http://127.0.0.1:8000/mcp/'，并确保选择 'Streamable HTTP' 作为传输协议。

npx @modelcontextprotocol/inspector

Inspector将显示服务器提供的 'receive_message' 和 'publish_message' 工具以及相关的Prompt模板。

4. 与LLM智能体集成

在您的LLM智能体应用中（例如基于OpenAI Agents SDK, OpenAI Python Library, PydanticAI Agent Framework等），按照您所使用的LLM框架的MCP客户端集成指南，利用上述“服务器配置”信息来连接并使用 'mqtt-mcp' 提供的功能。

LLM智能体可以通过自然语言指令来调用这些工具，例如：

  • 发布消息: 'Publish {"foo":"bar"} to topic "devices/foo" on 127.0.0.1:1883.'
  • 接收消息: 'Receive a message from topic "devices/bar", waiting up to 30 seconds.'

'mqtt-mcp' 将会解析这些指令，执行相应的MQTT操作，并将结果返回给LLM智能体。

信息

分类

通信与社交

访问项目