Content
# mcp2mqtt: A Bridge Connecting the Physical World and AI Large Models
[English](README_EN.md) | 简体中文
<div align="center">
<img src="docs/images/logo.png" alt="mcp2mqtt Logo" width="200"/>
<p>Control hardware through natural language, ushering in a new era of the Internet of Things</p>
</div>
## System Architecture
<div align="center">
<img src="docs/images/stru_chs.png" alt="System Architecture Diagram" width="800"/>
<p>mcp2mqtt System Architecture Diagram</p>
</div>
## Workflow
<div align="center">
<img src="docs/images/workflow_chs.png" alt="Workflow Diagram" width="800"/>
<p>mcp2mqtt Workflow Diagram</p>
</div>
## Project Vision
mcp2mqtt is a project that connects IoT devices to AI large models, seamlessly linking the physical world with AI large models through the Model Context Protocol (MCP) and MQTT protocol. The ultimate goals are to:
- Control your hardware devices using natural language
- Enable AI to respond in real-time and adjust physical parameters
- Equip your devices with the ability to understand and execute complex instructions
- Achieve interconnectivity between devices through the MQTT protocol
## Main Features
- **Intelligent MQTT Communication**
- Supports the publish/subscribe model of the MQTT protocol
- Compatible with various MQTT servers (such as Mosquitto, EMQ X, etc.)
- Supports QoS (Quality of Service) guarantees
- Supports topic filtering and message routing
- Real-time status monitoring and error handling
- **MCP Protocol Integration**
- Fully supports Model Context Protocol
- Supports resource management and tool invocation
- Flexible prompt system
- Command publishing and response via MQTT
## Configuration Instructions
### MQTT Configuration
```yaml
mqtt:
broker: "localhost" # MQTT server address
port: 1883 # MQTT server port
client_id: "mcp2mqtt_client" # MQTT client ID
username: "mqtt_user" # MQTT username
password: "mqtt_password" # MQTT password
keepalive: 60 # Keep connection time
topics:
command:
publish: "mcp/command" # Topic for sending commands
subscribe: "mcp/response" # Topic for receiving responses
status:
publish: "mcp/status" # Topic for sending status
subscribe: "mcp/control" # Topic for receiving control commands
```
### Command Configuration
```yaml
commands:
set_pwm:
command: "CMD_PWM {frequency}"
need_parse: false
data_type: "ascii"
prompts:
- "Set PWM to maximum"
- "Set PWM to minimum"
mqtt_topic: "mcp/pwm" # MQTT publish topic
response_topic: "mcp/pwm/response" # MQTT response topic
```
## MQTT Commands and Responses
### Command Format
Commands use a simple text format:
1. PWM Control:
- Command: `PWM {value}`
- Examples:
- `PWM 100` (maximum value)
- `PWM 0` (off)
- `PWM 50` (50%)
- Response: `CMD PWM {value} OK`
2. LED Control:
- Command: `LED {state}`
- Examples:
- `LED on` (turn on)
- `LED off` (turn off)
- Response: `CMD LED {state} OK`
3. Device Information:
- Command: `INFO`
- Response: `CMD INFO {device information}`
### Error Response
If an error occurs, the response format will be:
`ERROR: {error message}`
## Supported Clients
mcp2mqtt supports all clients that implement the MCP (MCP协议) protocol, as well as IoT devices that support the MQTT (MQTT协议) protocol:
| Client Type | Feature Support | Description |
|-------------------|-----------------|------------------------------------------|
| Claude Desktop | Full Support | Recommended, supports all MCP features |
| Continue | Full Support | Excellent development tool integration |
| Cline | Resources + Tools | Supports multiple AI providers |
| MQTT Devices | Publish/Subscribe | Supports all MQTT protocol IoT devices |
## Quick Start
### 1. Installation
#### Windows Users
Download [install.py](https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install.py)
```bash
python install.py
```
#### macOS Users
```bash
```
# Download and Install Script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
# Run the Installation Script
```bash
python3 install_macos.py
```
#### Ubuntu/Raspberry Pi Users
```bash
# Download and Install Script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py
# Run the Installation Script
```bash
python3 install_ubuntu.py
```
The installation script will automatically perform the following actions:
- Check the system environment
- Install necessary dependencies
- Create a default configuration file
- Configure Claude Desktop (if installed)
### Manual Step-by-Step Installation of Dependencies
```bash
windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh
```
The main dependency is the uv tool, so once Python, uv, and Claude or Cline are installed, you are good to go.
### Basic Configuration
Add the following content to your MCP client configuration file (such as Claude Desktop or Cline):
Note: If you are using the automatic installation, Claude Desktop will be configured automatically, and this step is not necessary.
Using the default configuration file:
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt"
]
}
}
}
```
> Note: After modifying the configuration, you need to restart Cline or Claude client software.
## Configuration Instructions
### Configuration File Location
The copied configuration file (`config.yaml`) can be placed in the following location:
User home directory (recommended for personal use)
```bash
# Windows System
C:\Users\Username\.mcp2mqtt\config.yaml
# macOS System
/Users/username/.mcp2mqtt/config.yaml
# Linux System
/home/username/.mcp2mqtt/config.yaml
```
- Applicable Scenario: Personal Configuration
- You need to create the `.mcp2mqtt` directory:
```bash
# Windows System (in Command Prompt)
mkdir "%USERPROFILE%\.mcp2mqtt"
# macOS/Linux System
mkdir -p ~/.mcp2mqtt
```
Specify the configuration file:
For example, to specify loading the Pico configuration file: Pico_config.yaml
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico" // Specify the configuration file name, no need to add _config.yaml suffix
]
}
}
}
```
To use multiple mqtt, we can add multiple mcp2mqtt services by specifying different configuration file names.
If you want to connect multiple devices, for example, to connect a second device:
Specify loading the Pico2 configuration file: Pico2_config.yaml
```json
{
"mcpServers": {
"mcp2mqtt2": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico2" // Specify the configuration file name, no need to add _config.yaml suffix
]
}
}
}
```
### Hardware Connection
1. Connect your device to the mqtt server via the network.
2. You can also use responder.py in the tests directory to simulate the device.
## Running Tests
### Start the Device Simulator
The project includes a device simulator in the `tests` directory. It can simulate a hardware device that is capable of:
- Responding to PWM (Pulse Width Modulation) control commands
- Providing device information
- Controlling LED status
To start the simulator:
```bash
python tests/responder.py
```
You should see output indicating that the simulator is running and has connected to the MQTT (Message Queuing Telemetry Transport) server.
### Start the Client Claude Desktop Version or Cline
<div align="center">
<img src="docs/images/test_output.png" alt="Cline Configuration Example" width="600"/>
<p>Example in Cline</p>
</div>
### Quick Start from Source
1. Install from Source
```bash
# Installation via Source Code:
git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt
# Create a Virtual Environment
uv venv .venv
# Activate Virtual Environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
# Install Development Dependencies
```bash
uv pip install --editable .
```
### MCP Client Configuration
When using a client that supports the MCP protocol (such as Claude Desktop or Cline), you need to add the following content to the client's configuration file:
Direct automatic installation configuration method
Source code development configuration method
#### Using Default Demo Parameters:
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uv",
"args": [
"--directory",
"your actual path/mcp2mqtt", // For example: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
"run",
"mcp2mqtt"
]
}
}
}
```
#### Specify Parameter File Name
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uv",
"args": [
"--directory",
"your actual path/mcp2mqtt", // For example: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
"run",
"mcp2mqtt",
"--config", // Optional parameter, specify the configuration file name
"Pico" // Optional parameter, specify the configuration file name, no need to add _config.yaml suffix
]
}
}
}
```
<div align="center">
<img src="docs/images/config.png" alt="Cline Configuration Example" width="600"/>
<p>Example in Cline</p>
</div>
### Configuration File Location
The configuration file (`config.yaml`) can be placed in different locations, and the program will search in the following order:
#### 1. Current Working Directory (suitable for development and testing)
- Path: `./config.yaml`
- Example: If you run the program in `C:\Projects`, it will look for `C:\Projects\config.yaml`
- Applicable Scenarios: Development and testing
- No special permissions required
#### 2. User Home Directory (Recommended for Personal Use)
```bash
# Windows System
C:\Users\Username\.mcp2mqtt\config.yaml
# macOS System
/Users/username/.mcp2mqtt/config.yaml
# Linux System
/home/username/.mcp2mqtt/config.yaml
```
- Applicable Scenario: Personal Configuration
- You need to create the `.mcp2mqtt` directory:
```bash
# Windows System (in Command Prompt)
mkdir "%USERPROFILE%\.mcp2mqtt"
# macOS/Linux System
mkdir -p ~/.mcp2mqtt
```
#### 3. System-Level Configuration (Suitable for Multi-User Environment)
```bash
# Windows System (Requires Administrator Privileges)
C:\ProgramData\mcp2mqtt\config.yaml
# macOS/Linux System (Requires root privileges)
/etc/mcp2mqtt/config.yaml
```
- Applicable Scenarios: Multi-user shared configuration
- Create directory and set permissions:
```bash
# Windows System (Run as Administrator)
mkdir "C:\ProgramData\mcp2mqtt"
# macOS/Linux System (Run as root)
sudo mkdir -p /etc/mcp2mqtt
sudo chown root:root /etc/mcp2mqtt
sudo chmod 755 /etc/mcp2mqtt
```
The program will search for the configuration file in the order mentioned above and will use the first valid configuration file it finds. Choose the appropriate location based on your needs:
- Development Testing: Use the current directory
- Personal Use: It is recommended to use the user home directory (recommended)
- Multi-user Environment: Use system-level configuration (ProgramData or /etc)
3. Run the server:
```bash
# Ensure the virtual environment is activated
.venv\Scripts\activate
# Run the Server (Using the default configuration config.yaml, the LOOP_BACK simulates the serial port in the example, no real serial port and serial devices are required)
uv run src/mcp2mqtt/server.py
or
uv run mcp2mqtt
# Run the Server (Using the Specified Configuration Pico_config.yaml)
uv run src/mcp2mqtt/server.py --config Pico
or
uv run mcp2mqtt --config Pico
```
## Documentation
- [Installation Guide](./docs/zh/installation.md)
- [API Documentation](./docs/zh/api.md)
- [Configuration Instructions](./docs/zh/configuration.md)
