Ioehub Mqtt MCP Server

IoEHub MQTT MCP서버

1.概述

本文描述了通过MQTT读取温度传感器数据并控制LED的模型上下文协议（MCP）服务器。该服务器基于FastMCP框架，使用JSON-RPC协议进行通信。

1.1结构图

MCP Client (Claude AI)

MCP Server (Python/FastMCP)

JSON-RPC （stdio） 请求/响应

MQTT Broker (172.30.1.100)

MQTT（JSON）

IoT Device (Temperature/LED)

MQTT（JSON）

1.2关键部件：

1. MCP客户端（Claude AI）

• 提供用户界面

• 向MCP服务器发送JSON-RPC请求

• 向用户显示结果

1. MCP服务器（Python/FastMCP）

• 处理客户端请求

• 与MQTT代理通信

• JSON-RPC和MQTT协议之间的转换

1. MQTT代理（172.30.1.100）

• MQTT消息的中心集线器

• 在服务器和设备之间路由消息

• 处理发布/订阅消息模式

1. 物联网设备（温度传感器/LED）

• 物理硬件设备

• 提供温度数据

• 根据命令控制LED状态

数据流：

1. 客户端→ 服务器：函数调用ioehub_mqtt_get_temperature（）或ioehub_mqtt_set_led（）

1. 服务器→ 代理：发布MQTT消息（主题：ioehub/mcp/命令）

1. 经纪人→ 设备：将命令转发到相应的设备

1. 设备→ Broker：发布带有数据的响应（主题：ioehub/mcp/response）

1. 经纪人→ 服务器：向订阅的服务器发送响应

1. 服务器→ 客户端：返回带有处理数据的函数调用结果

这种垂直布局清楚地显示了从客户端到服务器和代理再到物联网设备的分层通信流。

2.系统配置

• 框架：FastMCP
• 通信协议：MQTT，JSON-RPC 2.0
• 实施语言python
• 支持功能：温度测量，LED控制

3.MQTT设置

MQTT_BROKER = "172.30.1.100"
MQTT_PORT = 1883
MQTT_USERNAME = "ioehub"
MQTT_PASSWORD = "password"
MQTT_PUBLISH_TOPIC = "ioehub/mcp/command"
MQTT_SUBSCRIBE_TOPIC = "ioehub/mcp/response"

4.实现的功能

4.1温度测量（ioehub_mqtt_get_temperature)

• 说明：通过MQTT从温度传感器读取当前温度数据。
• 返回值：以字符串形式返回当前温度（摄氏度）
• 基本插针：13号

4.2 LED控制（ioehub_mqtt_set_led)

• 说明：通过MQTT控制指定插针的LED状态。
• 参数:

- pin （整数）：LED插针编号（默认值：0） - state （整数）：LED状态（1=开，0=关）

• 返回值：操作是否成功（真/假）

5.消息格式

5.1温度测量请求

{
  "function": "ioehub_mqtt_get_temperature",
  "params": {
    "pin": 13
  }
}

5.2温度测量响应

{
  "function": "ioehub_mqtt_get_temperature",
  "result": 26.5,
  "timestamp": "749817"
}

5.3 LED控制请求

{
  "function": "ioehub_mqtt_set_led",
  "params": {
    "pin": 0,
    "state": 1
  }
}

5.4 LED控制响应

{
  "function": "ioehub_mqtt_set_led",
  "result": true,
  "timestamp": "749820"
}

6.工作原理

1. 初始化服务器:

- 创建和设置MQTT客户端 - 设置订阅主题（ioehub/mcp/response） - 创建FastMCP实例

1. 连接过程:

- 连接到MQTT代理 - 等待后台线程接收消息

1. 处理函数调用:

- 调用MCP工具时运行该函数 - 通过MQTT发送请求 - 等待响应（最多5秒） - 返回结果

1. 消息接收处理:

- 从订阅主题接收消息 - JSON解析和数据提取 - 设置响应标志

7.错误处理

• 响应超时：如果5秒内没有响应，则返回默认值
• 解析JSON错误：处理格式错误的消息
• MQTT连接错误：连接失败时输出错误消息

8.使用方法

8.1运行服务器

python mcp_server.py

8.2在客户端调用函数

# MCP 클라이언트 예시
temperature = client.invoke("ioehub_mqtt_get_temperature")
print(f"현재 온도: {temperature}°C")

# LED 켜기
result = client.invoke("ioehub_mqtt_set_led", {"pin": 0, "state": 1})
print(f"LED 켜기 결과: {'성공' if result else '실패'}")

9.mcp server设置（windows claude desktop）

{
  "mcpServers": {
    "IoEHubMqttMcpServer": {
        "command": 
           "Your project path\\.venv\\Scripts\\python.exe",

        "args": [
	        "Your project path\\mcp_server.py"
	        ]

    }    
  }
}

10.构建python环境（windows）

cd "your project path"
uv venv .venv
uv pip install mcp
uv pip install paho-mqtt 

11.限制和注意事项

• MQTT代理必须正在运行。
• 在处理响应时，请检查“function”字段以识别正确的响应。
• 所有调试消息都必须输出到stderr，而不是stdout。
• 为了与实际硬件进行通信，必须在该设备上运行MQTT客户端。