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:
- Control your hardware devices using natural language
- AI responds in real-time and adjusts physical parameters
- Enable your devices 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 implementing 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
#### Windows Users
Download [install.py](https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install.py)
```bash
python install.py
```
#### macOS Users
```bash
# Download installation script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
# Run installation script
python3 install_macos.py
```
#### Ubuntu/Raspberry Pi Users
```bash
# Download installation script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py
# Run installation script
python3 install_ubuntu.py
```
The installation script will automatically perform the following actions:
- Check system environment
- Install necessary dependencies
- Create 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 (such as Claude Desktop or Cline) configuration file:
Note: If you use 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 configuration file:
For example, to specify loading the Pico configuration file: Pico_config.yaml
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico" // Specify configuration file name, do not add _config.yaml suffix
]
}
}
}
```
To use multiple MQTT instances, you can add multiple mcp2mqtt services by specifying different configuration file names.
If you want to connect multiple devices, such as connecting a second device:
Specify loading the Pico2 configuration file: Pico2_config.yaml
```json
{
"mcpServers": {
"mcp2mqtt2": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico2" // Specify 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
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 (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 development configuration method
#### Using default demonstration 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 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 above order, using 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 the 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)
