mcp2mqtt

Um serviço MCP para comunicação de dispositivos e controle PWM via protocolo MQTT.

GitHub

371

Experimente este MCPPatrocinado

Documentação

mcp2mqtt: 连接物理世界与AI大模型的桥梁

English | Português (BR)

Controle hardware com linguagem natural, inaugurando uma nova era da Internet das Coisas

Arquitetura do Sistema

Diagrama de arquitetura do sistema mcp2mqtt

Fluxo de Trabalho

Diagrama de fluxo de trabalho do mcp2mqtt

Visão do Projeto

mcp2mqtt é um projeto que conecta dispositivos IoT a grandes modelos de IA. Ele integra perfeitamente o mundo físico aos grandes modelos de IA por meio do Model Context Protocol (MCP) e do protocolo MQTT. O objetivo final é:

Controlar seus dispositivos de hardware usando linguagem natural
IA respondendo em tempo real e ajustando parâmetros físicos
Seus dispositivos com capacidade de entender e executar comandos complexos
Interconexão entre dispositivos por meio do protocolo MQTT

Principais Recursos

Comunicação MQTT Inteligente
- Suporte ao modo publish/subscribe do protocolo MQTT
- Suporte a vários servidores MQTT (como Mosquitto, EMQ X, etc.)
- Suporte à garantia de qualidade de serviço QoS
- Suporte a filtros de tópicos e roteamento de mensagens
- Monitoramento de status em tempo real e tratamento de erros
Integração com o Protocolo MCP
- Suporte completo ao Model Context Protocol
- Suporte a gerenciamento de recursos e chamadas de ferramentas
- Sistema flexível de prompts
- Publicação e resposta de comandos por meio do MQTT

Instruções de Configuração

Configuração 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"  # 接收控制命令的主题

Configuração 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 e Respostas MQTT

Formato de Comandos

Os comandos usam um formato de texto simples:

Controle PWM:
- Comando: PWM {值}
- Exemplos:
  - PWM 100 (valor máximo)
  - PWM 0 (desligado)
  - PWM 50 (50%)
- Resposta: CMD PWM {值} OK
Controle de LED:
- Comando: LED {状态}
- Exemplos:
  - LED on (ligado)
  - LED off (desligado)
- Resposta: CMD LED {状态} OK
Informações do dispositivo:
- Comando: INFO
- Resposta: CMD INFO {设备信息}

Respostas de Erro

Se ocorrer um erro, o formato da resposta será: ERROR: {错误信息}

Clientes Suportados

O mcp2mqtt suporta todos os clientes que implementam o protocolo MCP, bem como dispositivos IoT que suportam o protocolo MQTT:

Tipo de Cliente	Suporte a Recursos	Descrição
Claude Desktop	Suporte completo	Recomendado, suporta todos os recursos MCP
Continue	Suporte completo	Excelente integração com ferramentas de desenvolvimento
Cline	Recursos + Ferramentas	Suporta vários provedores de IA
Dispositivos MQTT	Publicar/Assinar	Suporta todos os dispositivos IoT com protocolo MQTT

Início Rápido

1. Instalação

Usuários Windows

Baixe o install.py

python install.py

Usuários macOS

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

# 运行安装脚本
python3 install_macos.py

Usuários Ubuntu/Raspberry Pi

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

# 运行安装脚本
python3 install_ubuntu.py

O script de instalação realizará automaticamente as seguintes operações:

Verificar o ambiente do sistema
Instalar as dependências necessárias
Criar o arquivo de configuração padrão
Configurar o Claude Desktop (se instalado)

Instalação Manual Passo a Passo das Dependências

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

A principal dependência é a ferramenta uv, portanto, quando python, uv e Claude ou Cline estiverem instalados, estará pronto.

Configuração Básica

Adicione o seguinte conteúdo ao arquivo de configuração do seu cliente MCP (como Claude Desktop ou Cline): Observação: se você usou a instalação automática, o Claude Desktop será configurado automaticamente, não sendo necessário este passo. Usando o arquivo de configuração padrão:

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

Observação: após modificar a configuração, é necessário reiniciar o Cline ou o cliente Claude

Instruções de Configuração

Localização do Arquivo de Configuração

Copie o arquivo de configuração (config.yaml) e coloque-o nos seguintes locais: Diretório do usuário (recomendado para uso pessoal)

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

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

# Linux系统
/home/用户名/.mcp2mqtt/config.yaml

Cenário de uso: configuração pessoal

É necessário criar o diretório .mcp2mqtt:

# Windows系统（在命令提示符中）
mkdir "%USERPROFILE%\.mcp2mqtt"

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

Arquivo de configuração específico: Por exemplo, para carregar o arquivo de configuração Pico: Pico_config.yaml

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

Para usar vários MQTT, podemos adicionar vários serviços mcp2mqtt especificando diferentes nomes de arquivos de configuração. Para conectar vários dispositivos, por exemplo, para conectar um segundo dispositivo: Carregar o arquivo de configuração Pico2: Pico2_config.yaml

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

Conexão de Hardware

Conecte seu dispositivo ao servidor MQTT pela rede
Você também pode usar o responder.py no diretório tests para simular um dispositivo

Executando Testes

Iniciando o Simulador de Dispositivo

O projeto inclui um simulador de dispositivo no diretório tests. Ele pode simular um dispositivo de hardware, capaz de:

Responder a comandos de controle PWM
Fornecer informações do dispositivo
Controlar o estado do LED

Iniciando o simulador:

python tests/responder.py

Você deve ver o simulador em execução e a saída de informações indicando a conexão com o servidor MQTT.

Iniciando o Cliente Claude Desktop ou Cline

Exemplo no Cline

Início Rápido a partir do Código-Fonte

Instalar a partir do código-fonte

# 通过源码安装：
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 .

Configuração do Cliente MCP

Ao usar clientes que suportam o protocolo MCP (como Claude Desktop ou Cline), é necessário adicionar o seguinte conteúdo ao arquivo de configuração do cliente: Configuração para instalação automática direta Configuração para desenvolvimento a partir do código-fonte

Usando parâmetros de demonstração padrão:

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

Especificando o nome do arquivo 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后缀
            ]
        }
    }
}

Exemplo no Cline

### Localização do Arquivo de Configuração O arquivo de configuração (`config.yaml`) pode ser colocado em diferentes locais. O programa buscará na seguinte ordem: #### 1. Diretório de trabalho atual (adequado para desenvolvimento e testes) - Caminho: `./config.yaml` - Exemplo: se você executar o programa em `C:\Projects`, ele procurará em `C:\Projects\config.yaml` - Cenário de uso: desenvolvimento e testes - Não requer permissões especiais

2. Diretório do usuário (recomendado para uso pessoal)

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

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

# Linux系统
/home/用户名/.mcp2mqtt/config.yaml

Cenário de uso: configuração pessoal

É necessário criar o diretório .mcp2mqtt:

# Windows系统（在命令提示符中）
mkdir "%USERPROFILE%\.mcp2mqtt"

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

3. Configuração em nível de sistema (adequado para ambientes multiusuário)

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

# macOS/Linux系统（需要root权限）
/etc/mcp2mqtt/config.yaml

Cenário de uso: configuração compartilhada entre vários usuários

Criar o diretório e definir permissões:

# Windows系统（以管理员身份运行）
mkdir "C:\ProgramData\mcp2mqtt"

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

O programa buscará o arquivo de configuração na ordem acima, usando o primeiro arquivo válido encontrado. Escolha o local adequado conforme sua necessidade:

Desenvolvimento e testes: use o diretório atual
Uso pessoal: recomendado usar o diretório do usuário (recomendado)
Ambiente multiusuário: use a configuração em nível de sistema (ProgramData ou /etc)

Executar o 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