IoEHub MQTT MCP 서버

IoEHub MQTT MCP 서버

1. 개요

이 문서는 MQTT를 통해 온도 센서 데이터를 읽고 LED를 제어하는 MCP(Model Context Protocol) 서버를 설명합니다. 이 서버는 FastMCP 프레임워크를 기반으로 하며, JSON-RPC 프로토콜을 사용하여 통신합니다.

1.1 구조도

MCP Client (Claude AI) MCP Server (Python/FastMCP)

JSON-RPC (stdio) Request/Response

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 Broker 通信

• 在 JSON-RPC 和 MQTT 协议之间进行转换

1. MQTT Broker（172.30.1.100）

• MQTT 消息的中心枢纽

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

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

1. IoT 设备（温度传感器/LED）

• 实体硬件设备

• 提供温度数据

• 根据命令控制 LED 状态

数据流：

1. 客户端 → 服务：调用函数 ioehub_mqtt_get_temperature() 或 ioehub_mqtt_set_led()

2. 服务 → Broker：发布 MQTT 消息（主题：ioehub/mcp/command）

3. Broker → 设备：将命令转发到相应设备

4. 设备 → Broker：发布包含数据的响应（主题：ioehub/mcp/response）

5. Broker → 服务：将响应发送给已订阅的服务

6. 服务 → 客户端：返回包含已处理数据的函数调用结果

这种垂直布局清晰地展示了通信从客户端经过服务和 Broker 到 IoT 设备的层级流程。

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=关闭）
• 返回值：操作是否成功（True/False）

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 实例

2. 连接流程：

   • 连接到 MQTT Broker
   • 在后台线程中等待接收消息

3. 函数调用处理：

   • 调用 MCP 工具时执行相应函数
   • 通过 MQTT 发送请求
   • 等待响应（最长 5 秒）
   • 返回结果

4. 消息接收处理：

   • 从订阅主题接收消息
   • 解析 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 服务配置（Windows Claude 桌面版）

{
  "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 Broker 必须处于运行状态。
• 处理响应时，请检查 function 字段以识别相应的响应。
• 所有调试消息都必须输出到 stderr，而不是 stdout。
• 要与实际硬件通信，必须在相应设备上运行 MQTT 客户端。