Content
# Tool List
[English](README_EN.md)
<div align="center">
<img src="docs/images/logo.png" alt="mcp2mqtt Logo" width="200"/>
<p>Controlling Hardware with Natural Language, Opening a New Era of IoT</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. It seamlessly connects the physical world with AI large models through the Model Context Protocol (MCP) and MQTT protocol. The goal is to:
- Control your hardware devices with natural language
- AI responds and adjusts physical parameters in real-time
- Enable your devices to understand and execute complex instructions
- Achieve device-to-device communication through the MQTT protocol
## Key Features
- **Intelligent MQTT Communication**
- Supports MQTT protocol publish/subscribe mode
- Supports multiple MQTT servers (e.g., Mosquitto, EMQ X)
- Supports QoS service quality assurance
- Supports topic filtering and message routing
- Real-time status monitoring and error handling
- **MCP Protocol Integration**
- Complete support for Model Context Protocol
- Supports resource management and tool invocation
- Flexible prompt word system
- Command publishing and response through 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 # Keepalive 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:
- "Put PWM to maximum"
- "Put 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}`
- Example:
- `PWM 100` (maximum value)
- `PWM 0` (off)
- `PWM 50` (50%)
- Response: `CMD PWM {value} OK`
2. LED Control:
- Command: `LED {status}`
- Example:
- `LED on` (on)
- `LED off` (off)
- Response: `CMD LED {status} 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 and 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 | Resource + tool | Supports multiple AI providers |
| MQTT Device | 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 complete the following operations:
- 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 when Python, uv, and Claude or Cline are installed, you are ready to go.
### Basic Configuration
Add the following content to your MCP client (e.g., Claude Desktop or Cline) configuration file:
Note: If you use automatic installation, Claude Desktop will be automatically configured, and this step is not required.
Use the default configuration file:
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt"
]
}
}
}
```
> Note: Restart the Cline or Claude client software after modifying the configuration
## Configuration Instructions
### Configuration File Location
Copy the configuration file (`config.yaml`) can be placed in:
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
- Need to create `.mcp2mqtt` directory:
```bash
# Windows system (in command prompt)
mkdir "%USERPROFILE%\.mcp2mqtt"
# macOS/Linux system
mkdir -p ~/.mcp2mqtt
```
Specify the configuration file:
For example, specify loading Pico configuration file: Pico_config.yaml
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico" // Specify configuration file name, no need to add _config.yaml suffix
]
}
}
}
```
To use multiple MQTTs, we can add multiple mcp2mqtt services with different configuration file names.
### Hardware Connection
1. Connect your device to the MQTT server through the network
2. You can also use the responder.py in the tests directory to simulate the device
## Run Test
### Start Device Simulator
The project contains a device simulator in the `tests` directory. It can simulate a hardware device that:
- Responds to PWM control commands
- Provides device information
- Controls LED status
Start the simulator:
```bash
python tests/responder.py
```
You should see the output 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 code:
```bash
# Install from source code:
git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt
# Create virtual environment
uv venv .venv
# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
# Install development dependencies
uv pip install --editable .
```
### MCP Client Configuration
When using an MCP protocol-supported client (e.g., Claude Desktop or Cline), add the following content to the client configuration file:
Direct automatic installation configuration
Source code development configuration
#### Use default demonstration parameters:
```json
{
"mcpServers": {
"mcp2mqtt": {
"command": "uv",
"args": [
"--directory",
"Your actual path/mcp2mqtt", // e.g., "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", // e.g., "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, 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 scenario: 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
- Need to create `.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 scenario: 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 above order and use the first valid configuration file found. Choose the appropriate location according to 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 default configuration config.yaml in the case)
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/en/installation.md)
- [API Documentation](./docs/en/api.md)
- [Configuration Instructions](./docs/en/configuration.md)
