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 with 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
## Key Features
- **Intelligent MQTT Communication**
- Supports MQTT protocol's publish/subscribe model
- Compatible with various MQTT servers (e.g., 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 the 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-alive 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 protocol, as well as IoT devices that support the 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
#### For Windows Users
Download [install.py](https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install.py)
```bash
python install.py
```
#### For macOS Users
```bash
# Download the installation script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
# Run the installation script
python3 install_macos.py
```
#### For Ubuntu/Raspberry Pi Users
```bash
# Download the installation script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py
# Run the installation script
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 (e.g., Claude Desktop or Cline):
Note: If you used the automatic installation, Claude Desktop will be configured automatically, and this step is not needed.
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 configuration file (`config.yaml`) can be placed in the following locations:
User home directory (recommended for personal use)
```bash
# Windows
C:\Users\Username\.mcp2mqtt\config.yaml
# macOS
/Users/Username/.mcp2mqtt/config.yaml
# Linux
/home/Username/.mcp2mqtt/config.yaml
```
- Applicable Scenario: Personal configuration
- You need to create the `.mcp2mqtt` directory:
```bash
# Windows (in Command Prompt)
mkdir "%USERPROFILE%\.mcp2mqtt"
# macOS/Linux
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, do not add _config.yaml suffix
]
}
}
}
```
To use multiple MQTT instances, you can add multiple mcp2mqtt services with 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, do not add _config.yaml suffix
]
}
}
}
```
### Hardware Connection
1. Connect your device to the MQTT server via the network.
2. You can also use the responder.py in the tests directory to simulate a device.
## Running Tests
### Start Device Simulator
The project includes a device simulator in the `tests` directory. It can simulate a hardware device that can:
- Respond to PWM control commands
- Provide device information
- Control LED status
Start the simulator:
```bash
python tests/responder.py
```
You should see output indicating that the simulator is running and connected to the MQTT server.
### Start Client Claude Desktop 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 Code
1. Install from source
```bash
# Install from source:
git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt
# Create a virtual environment
uv venv .venv
# Activate the virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
# Install development dependencies
uv pip install --editable .
```
### MCP Client Configuration
When using a client that supports the MCP protocol (e.g., Claude Desktop or Cline), you need to add the following content to the client's configuration file:
Direct automatic installation configuration method
Source 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 configuration file name
"Pico" // Optional parameter, specify configuration file name, do not 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 Scenario: Development and testing
- No special permissions required
#### 2. User Home Directory (recommended for personal use)
```bash
# Windows
C:\Users\Username\.mcp2mqtt\config.yaml
# macOS
/Users/Username/.mcp2mqtt/config.yaml
# Linux
/home/Username/.mcp2mqtt/config.yaml
```
- Applicable Scenario: Personal configuration
- You need to create the `.mcp2mqtt` directory:
```bash
# Windows (in Command Prompt)
mkdir "%USERPROFILE%\.mcp2mqtt"
# macOS/Linux
mkdir -p ~/.mcp2mqtt
```
#### 3. System-Level Configuration (suitable for multi-user environments)
```bash
# Windows (requires administrator privileges)
C:\ProgramData\mcp2mqtt\config.yaml
# macOS/Linux (requires root privileges)
/etc/mcp2mqtt/config.yaml
```
- Applicable Scenario: Shared configuration for multiple users
- Create the directory and set permissions:
```bash
# Windows (run as administrator)
mkdir "C:\ProgramData\mcp2mqtt"
# macOS/Linux (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 use the first valid configuration file found. Choose the appropriate location based on your needs:
- Development and testing: Use the current directory
- Personal use: Recommended to use the user home directory
- 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 example uses LOOP_BACK to simulate serial port, no real serial port and device needed)
uv run src/mcp2mqtt/server.py
or
uv run mcp2mqtt
# Run the server (using 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)
