Mcp2mqtt

🚀 mcp2mqtt Server Guide

This guide provides a detailed introduction to the installation, configuration, and operation of the mcp2mqtt server, helping you quickly set up and use this service.

🚀 Quick Start

📦 Installation

Step 1: Create a Virtual Environment

uv venv .venv

Step 2: Activate the Virtual Environment

• Windows:

.venv\Scripts\activate

• Linux/macOS:

source .venv/bin/activate

Step 3: Install Development Dependencies

uv pip install --editable .

⚙️ Configuration

Add the following content to the configuration file of clients supporting the MCP protocol (such as Claude Desktop or Cline):

Use Default Demo Parameters

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uv",
            "args": [
                "--directory",
                "Your actual path/mcp2mqtt",  // Example: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
                "run",
                "mcp2mqtt"
            ]
        }
    }
}

Specify the Parameter File Name

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uv",
            "args": [
                "--directory",
                "Your actual path/mcp2mqtt",  // Example: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
                "run",
                "mcp2mqtt",
                "--config", // Optional parameter to specify the configuration file name
                "Pico"  // Optional parameter to specify the configuration file name, no need to add the _config.yaml suffix
            ]
        }
    }
}

📂 Configuration File Location

The program searches for configuration files 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

2. User Home Directory (Recommended for Personal Use)

# Windows
C:\Users\Username\.mcp2mqtt\config.yaml

# macOS
/Users/Username/.mcp2mqtt/config.yaml

# Linux
/home/Username/.mcp2mqtt/config.yaml

3. System-Level Configuration (Suitable for Multi-User Environments)

# Windows (Requires Administrator Privileges)
C:\ProgramData\mcp2mqtt\config.yaml

# macOS/Linux (Requires Root Privileges)
/etc/mcp2mqtt/config.yaml

The program will search for configuration files 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: It is recommended to use the user home directory.
• Multi-User Environments: Use system-level configuration.

▶️ Run the Server

# Make sure the virtual environment is activated
.venv\Scripts\activate

# Run the server (Use the default configuration config.yaml. In the example, LOOP_BACK is used to simulate the serial port, no real serial port or serial device is required)
uv run src/mcp2mqtt/Server

📚 Documentation

• API Documentation: mcp2mqtt API Documentation
• Related Images:
  • Configuration Example Image
  • Running Interface Image

For further assistance, please refer to the Official Documentation or contact the support team.