mcp2mqtt

Un servicio MCP para comunicación de dispositivos y control PWM mediante el protocolo MQTT.

GitHub
371
Prueba este MCPPatrocinado

Documentación

mcp2mqtt: El puente que conecta el mundo físico con los grandes modelos de IA

English | 简体中文

mcp2mqtt Logo

Controla hardware mediante lenguaje natural, inaugurando una nueva era del IoT

Arquitectura del sistema

系统架构图

Diagrama de arquitectura del sistema mcp2mqtt

Flujo de trabajo

工作流程图

Diagrama de flujo de trabajo de mcp2mqtt

Visión del proyecto

mcp2mqtt es un proyecto que conecta dispositivos IoT con grandes modelos de IA. A través del Protocolo de Contexto de Modelo (MCP) y el protocolo MQTT, conecta sin problemas el mundo físico con los grandes modelos de IA. El resultado final:

  • Controla tus dispositivos de hardware con lenguaje natural
  • La IA responde en tiempo real y ajusta los parámetros físicos
  • Tus dispositivos adquieren la capacidad de comprender y ejecutar instrucciones complejas
  • Interconexión entre dispositivos mediante el protocolo MQTT

Características principales

  • Comunicación MQTT inteligente

    • Soporta el modo publicación/suscripción del protocolo MQTT
    • Compatible con múltiples servidores MQTT (como Mosquitto, EMQ X, etc.)
    • Garantía de calidad de servicio QoS
    • Filtrado de temas y enrutamiento de mensajes
    • Monitoreo de estado en tiempo real y manejo de errores

  • Integración del protocolo MCP

    • Soporte completo del Protocolo de Contexto de Modelo
    • Gestión de recursos y llamadas a herramientas
    • Sistema flexible de indicaciones
    • Publicación y respuesta de comandos a través de MQTT

Instrucciones de configuración

Configuración MQTT

mqtt:
  broker: "localhost"  # MQTT服务器地址
  port: 1883  # MQTT服务器端口
  client_id: "mcp2mqtt_client"  # MQTT客户端ID
  username: "mqtt_user"  # MQTT用户名
  password: "mqtt_password"  # MQTT密码
  keepalive: 60  # 保持连接时间
  topics:
    command:
      publish: "mcp/command"  # 发送命令的主题
      subscribe: "mcp/response"  # 接收响应的主题
    status:
      publish: "mcp/status"  # 发送状态的主题
      subscribe: "mcp/control"  # 接收控制命令的主题

Configuración de comandos

commands:
  set_pwm:
    command: "CMD_PWM {frequency}"
    need_parse: false
    data_type: "ascii"
    prompts:
      - "把PWM调到最大"
      - "把PWM调到最小"
    mqtt_topic: "mcp/pwm"  # MQTT发布主题
    response_topic: "mcp/pwm/response"  # MQTT响应主题

Comandos y respuestas MQTT

Formato de comandos

Los comandos utilizan un formato de texto simple:

  1. Control PWM:

    • Comando: PWM {值}
    • Ejemplos:
      • PWM 100 (valor máximo)
      • PWM 0 (apagado)
      • PWM 50 (50%)
    • Respuesta: CMD PWM {值} OK

  2. Control LED:

    • Comando: LED {状态}
    • Ejemplos:
      • LED on (encendido)
      • LED off (apagado)
    • Respuesta: CMD LED {状态} OK

  3. Información del dispositivo:

    • Comando: INFO
    • Respuesta: CMD INFO {设备信息}

Respuesta de error

Si ocurre un error, el formato de respuesta será: ERROR: {错误信息}

Clientes compatibles

mcp2mqtt es compatible con todos los clientes que implementan el protocolo MCP, así como con dispositivos IoT que soportan el protocolo MQTT:

Tipo de clienteSoporte de característicasDescripción
Claude DesktopSoporte completoRecomendado, admite todas las funciones de MCP
ContinueSoporte completoExcelente integración con herramientas de desarrollo
ClineRecursos + herramientasAdmite múltiples proveedores de IA
Dispositivos MQTTPublicación/suscripciónAdmite todos los dispositivos IoT con protocolo MQTT

Inicio rápido

1. Instalación

Usuarios de Windows

Descarga install.py

python install.py

Usuarios de macOS

# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py

# 运行安装脚本
python3 install_macos.py

Usuarios de Ubuntu/Raspberry Pi

# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py

# 运行安装脚本
python3 install_ubuntu.py

El script de instalación realizará automáticamente las siguientes operaciones:

  • Verificar el entorno del sistema
  • Instalar las dependencias necesarias
  • Crear el archivo de configuración predeterminado
  • Configurar Claude Desktop (si está instalado)

Instalación manual paso a paso de dependencias

windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh

La dependencia principal es la herramienta uv, así que una vez que python, uv y Claude o Cline estén instalados, todo estará listo.

Configuración básica

Agrega el siguiente contenido al archivo de configuración de tu cliente MCP (como Claude Desktop o Cline): Nota: si usas la instalación automática, Claude Desktop se configurará automáticamente y no se necesita este paso. Usando el archivo de configuración predeterminado:

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uvx",
            "args": [
                "mcp2mqtt"
            ]
        }
    }
}

Nota: después de modificar la configuración, debes reiniciar el software cliente Cline o Claude.

Instrucciones de configuración

Ubicación del archivo de configuración

Copia el archivo de configuración (config.yaml) y colócalo en: Directorio de inicio del usuario (recomendado para uso personal)

# Windows系统
C:\Users\用户名\.mcp2mqtt\config.yaml

# macOS系统
/Users/用户名/.mcp2mqtt/config.yaml

# Linux系统
/home/用户名/.mcp2mqtt/config.yaml
  • Escenario de uso: configuración personal
  • Necesitas crear el directorio .mcp2mqtt: 
    # Windows系统（在命令提示符中）
mkdir "%USERPROFILE%\.mcp2mqtt"

# macOS/Linux系统
mkdir -p ~/.mcp2mqtt

Especificar archivo de configuración: Por ejemplo, para cargar el archivo de configuración Pico: Pico_config.yaml

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uvx",
            "args": [
                "mcp2mqtt",
                "--config",
                "Pico"  //指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}

Para poder usar múltiples MQTT, podemos agregar varios servicios mcp2mqtt especificando diferentes nombres de archivo de configuración. Si deseas conectar múltiples dispositivos, por ejemplo, para conectar un segundo dispositivo: Especificar la carga del archivo de configuración Pico2: Pico2_config.yaml

{
    "mcpServers": {
        "mcp2mqtt2": {
            "command": "uvx",
            "args": [
                "mcp2mqtt",
                "--config",
                "Pico2"  //指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}

Conexión de hardware

  1. Conecta tu dispositivo al servidor MQTT a través de la red
  2. También puedes usar responder.py en el directorio tests para simular un dispositivo

Ejecutar pruebas

Iniciar el simulador de dispositivos

El proyecto incluye un simulador de dispositivos en el directorio tests. Puede simular un dispositivo de hardware capaz de:

  • Responder a comandos de control PWM
  • Proporcionar información del dispositivo
  • Controlar el estado del LED

Iniciar el simulador:

python tests/responder.py

Deberías ver la salida que indica que el simulador está en ejecución y conectado al servidor MQTT.

Iniciar el cliente Claude Desktop o Cline

Cline Configuration Example

Ejemplo en Cline

Inicio rápido desde el código fuente

  1. Instalar desde el código fuente
# 通过源码安装：
git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt

# 创建虚拟环境
uv venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 安装开发依赖
uv pip install --editable .

Configuración del cliente MCP

Al usar un cliente compatible con el protocolo MCP (como Claude Desktop o Cline), debes agregar el siguiente contenido al archivo de configuración del cliente: Método de configuración con instalación automática directa Método de configuración para desarrollo desde el código fuente

Usando los parámetros de demostración predeterminados:

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uv",
            "args": [
                "--directory",
                "你的实际路径/mcp2mqtt",  // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
                "run",
                "mcp2mqtt"
            ]
        }
    }
}

Especificar nombre de archivo de parámetros

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uv",
            "args": [
                "--directory",
                "你的实际路径/mcp2mqtt",  // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
                "run",
                "mcp2mqtt",
                "--config", // 可选参数，指定配置文件名
                "Pico"  // 可选参数，指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}
Cline Configuration Example

Ejemplo en Cline

### Ubicación del archivo de configuración El archivo de configuración (`config.yaml`) puede colocarse en diferentes ubicaciones. El programa buscará en el siguiente orden: #### 1. Directorio de trabajo actual (adecuado para desarrollo y pruebas) - Ruta: `./config.yaml` - Ejemplo: si ejecutas el programa en `C:\Projects`, buscará `C:\Projects\config.yaml` - Escenario de uso: desarrollo y pruebas - No requiere permisos especiales

2. Directorio de inicio del usuario (recomendado para uso personal)

# Windows系统
C:\Users\用户名\.mcp2mqtt\config.yaml

# macOS系统
/Users/用户名/.mcp2mqtt/config.yaml

# Linux系统
/home/用户名/.mcp2mqtt/config.yaml
  • Escenario de uso: configuración personal
  • Necesitas crear el directorio .mcp2mqtt: 
    # Windows系统（在命令提示符中）
mkdir "%USERPROFILE%\.mcp2mqtt"

# macOS/Linux系统
mkdir -p ~/.mcp2mqtt

3. Configuración a nivel de sistema (adecuado para entornos multiusuario)

# Windows系统（需要管理员权限）
C:\ProgramData\mcp2mqtt\config.yaml

# macOS/Linux系统（需要root权限）
/etc/mcp2mqtt/config.yaml
  • Escenario de uso: configuración compartida multiusuario
  • Crear directorio y establecer permisos: 
    # Windows系统（以管理员身份运行）
mkdir "C:\ProgramData\mcp2mqtt"

# macOS/Linux系统（以root身份运行）
sudo mkdir -p /etc/mcp2mqtt
sudo chown root:root /etc/mcp2mqtt
sudo chmod 755 /etc/mcp2mqtt

El programa buscará el archivo de configuración en el orden anterior y usará el primer archivo válido que encuentre. Elige la ubicación adecuada según tus necesidades:

  • Desarrollo y pruebas: usa el directorio actual
  • Uso personal: se recomienda el directorio de inicio del usuario (recomendado)
  • Entorno multiusuario: usa la configuración a nivel de sistema (ProgramData o /etc)
  1. Ejecutar el servidor:
# 确保已激活虚拟环境
.venv\Scripts\activate

# 运行服务器（使用默认配置config.yaml 案例中用的LOOP_BACK 模拟串口，无需真实串口和串口设备）
uv run src/mcp2mqtt/server.py
或
uv run mcp2mqtt
# 运行服务器（使用指定配置Pico_config.yaml）
uv run src/mcp2mqtt/server.py --config Pico
或
uv run mcp2mqtt --config Pico

Documentación