MCP 服务器

IoEHub MQTT MCP 서버

ioehub

研究与数据

访问服务器

README

IoEHub MQTT MCP 协议

1. 简介

本示例演示了 MQTT 协议如何与一个简单的（但可扩展的）LED 控制和温度读取的 MCP (模型上下文协议) 架构集成。本示例使用 FastMCP 库来简化 JSON-RPC 协议的处理。

1.1 架构图

<svg viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg">
  <!-- MCP Client Box -->
  <rect x="50" y="100" width="200" height="120" rx="5" ry="5" fill="white" stroke="black" stroke-width="2"/>
  <text x="150" y="140" text-anchor="middle" font-family="Arial" font-size="16" font-weight="bold">MCP Client</text>
  <text x="150" y="165" text-anchor="middle" font-family="Arial" font-size="14">(Claude AI)</text>

  <!-- MCP Server Box -->
  <rect x="550" y="100" width="200" height="120" rx="5" ry="5" fill="white" stroke="black" stroke-width="2"/>
  <text x="650" y="140" text-anchor="middle" font-family="Arial" font-size="16" font-weight="bold">MCP Server</text>
  <text x="650" y="165" text-anchor="middle" font-family="Arial" font-size="14">(Python/FastMCP)</text>

  <!-- Arrow definitions -->
  <defs>
    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="black"/>
    </marker>
  </defs>

  <!-- JSON-RPC Arrow -->
  <line x1="250" y1="135" x2="550" y2="135" stroke="black" stroke-width="2" marker-end="url(#arrowhead)" stroke-dasharray="5,5"/>
  <line x1="550" y1="165" x2="250" y2="165" stroke="black" stroke-width="2" marker-end="url(#arrowhead)"/>
  
  <!-- Labels for JSON-RPC -->
  <text x="400" y="120" text-anchor="middle" font-family="Arial" font-size="14" font-weight="bold">JSON-RPC</text>
  <text x="400" y="140" text-anchor="middle" font-family="Arial" font-size="12">(stdio)</text>
  <text x="400" y="185" text-anchor="middle" font-family="Arial" font-size="12">Request/Response</text>
  
  <!-- MQTT Broker Box -->
  <rect x="300" y="300" width="200" height="120" rx="5" ry="5" fill="white" stroke="black" stroke-width="2"/>
  <text x="400" y="340" text-anchor="middle" font-family="Arial" font-size="16" font-weight="bold">MQTT Broker</text>
  <text x="400" y="365" text-anchor="middle" font-family="Arial" font-size="14">(172.30.1.100)</text>

  <!-- Bidirectional arrows for MQTT connections -->
  <!-- Between Server and Broker -->
  <line x1="650" y1="220" x2="500" y2="280" stroke="black" stroke-width="2"/>
  <line x1="500" y1="280" x2="520" y2="273" stroke="black" stroke-width="2"/>
  <line x1="500" y1="280" x2="507" y2="295" stroke="black" stroke-width="2"/>
  
  <line x1="500" y1="340" x2="650" y2="220" stroke="black" stroke-width="2"/>
  <line x1="650" y1="220" x2="635" y2="230" stroke="black" stroke-width="2"/>
  <line x1="650" y1="220" x2="640" y2="212" stroke="black" stroke-width="2"/>
  
  <!-- MQTT Label for Server-Broker -->
  <text x="550" y="250" text-anchor="middle" font-family="Arial" font-size="14" font-weight="bold">MQTT (JSON)</text>

  <!-- IoT Device Box -->
  <rect x="300" y="500" width="200" height="100" rx="5" ry="5" fill="white" stroke="black" stroke-width="2"/>
  <text x="400" y="535" text-anchor="middle" font-family="Arial" font-size="16" font-weight="bold">IoT Device</text>
  <text x="400" y="560" text-anchor="middle" font-family="Arial" font-size="14">(Temperature/LED)</text>

  <!-- Bidirectional arrows for MQTT connections -->
  <!-- Between Broker and Device -->
  <line x1="385" y1="420" x2="385" y2="500" stroke="black" stroke-width="2"/>
  <line x1="385" y1="500" x2="378" y2="480" stroke="black" stroke-width="2"/>
  <line x1="385" y1="500" x2="392" y2="480" stroke="black" stroke-width="2"/>
  
  <line x1="415" y1="500" x2="415" y2="420" stroke="black" stroke-width="2"/>
  <line x1="415" y1="420" x2="408" y2="440" stroke="black" stroke-width="2"/>
  <line x1="415" y1="420" x2="422" y2="440" stroke="black" stroke-width="2"/>
  
  <!-- MQTT Label for Broker-Device -->
  <text x="470" y="460" text-anchor="middle" font-family="Arial" font-size="14" font-weight="bold">MQTT (JSON)</text>
</svg>

1.2 主要组件:

MCP 客户端 (Claude AI)

提供用户界面
发送 JSON-RPC 请求到 MCP 服务器
向用户显示结果

MCP 服务器 (Python/FastMCP)

处理客户端请求
与 MQTT Broker 通信
在 JSON-RPC 和 MQTT 协议之间进行转换

MQTT Broker (172.30.1.100)

MQTT 消息的中心枢纽
在服务器和设备之间路由消息
处理发布/订阅消息模式

IoT 设备 (温度传感器/LED)

物理硬件设备
提供温度数据
基于命令控制 LED 状态

数据流:

客户端 -> 服务器: 函数调用 ioehub_mqtt_get_temperature() 或 ioehub_mqtt_set_led()
服务器 -> Broker: 发布 MQTT 消息 (topic: ioehub/mcp/command)
Broker -> 设备: 将命令转发到适当的设备
设备 -> Broker: 发布带有数据的响应 (topic: ioehub/mcp/response)
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. 调试技巧

确保连接正常:
- MQTT 客户端能够成功连接到 MQTT Broker。
- 订阅主题正确 (ioehub/mcp/response)
- FastMCP 服务正常运行。
检查消息格式:
- MQTT 消息是否符合预期的格式。
- 确保所有必需的参数都已正确传递。
查看日志信息:
- MCP 服务日志中是否有任何错误或警告消息。
- MQTT 客户端的请求是否正确发送。
- 响应是否正确返回 (包括错误信息)。
测试消息传递流程:
- 确保订阅主题的正确性。
- JSON 格式的正确性。
- 响应的正确性。

7. 常见问题

响应超时问题: 确保服务器能够及时响应请求。
JSON 格式错误: 验证请求和响应的 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 客户端应该能够成功连接到 MQTT Broker。
响应应该包含 'function' 字段对应于请求的函数。
确保所有标准输出 stdout 和 stderr 都被正确处理。
确保正确配置了 MQTT 客户端的连接参数。

推荐服务器

Crypto Price & Market Analysis MCP Server

一个模型上下文协议 (MCP) 服务器，它使用 CoinCap API 提供全面的加密货币分析。该服务器通过一个易于使用的界面提供实时价格数据、市场分析和历史趋势。 (Alternative, slightly more formal and technical translation): 一个模型上下文协议 (MCP) 服务器，利用 CoinCap API 提供全面的加密货币分析服务。该服务器通过用户友好的界面，提供实时价格数据、市场分析以及历史趋势数据。

精选

TypeScript