mqtt-mcp-server 1.0.1

MQTT Model Context Protocol Server for AI-powered smart home control

MQTT MCP Server

MCP server that connects AI assistants to MQTT brokers for smart home automation and IoT device control.

What it does:

• Discovers MQTT topics and devices on your network
• Reads sensor values and device states
• Sends commands to control devices
• Monitors real-time MQTT events

Use cases:

• Control smart home devices through AI assistants
• Monitor IoT sensor networks
• Automate home automation workflows
• Debug MQTT integrations

---

Quick Navigation

Choose your system:

Linux

• Claude Code ⭐ Recommended
• Codex CLI
• Cursor
• Cline
• Other Clients

macOS

• Claude Code
• Codex CLI
• Claude Desktop
• Cursor
• Cline
• Other Clients

Windows

• Claude Code
• Codex CLI
• Claude Desktop
• Cursor
• Cline
• Other Clients

---

Linux

Linux • Claude Code

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Claude Code

claude mcp add --transport stdio mqtt \
  --env MQTT_HOST=YOUR_BROKER_IP \
  --env MQTT_PORT=1883 \
  --env MQTT_USERNAME=YOUR_USERNAME \
  --env MQTT_PASSWORD=YOUR_PASSWORD \
  -- python3 -m mqtt_mcp.server

Step 3: Verify

claude mcp list

You should see: mqtt: python3 -m mqtt_mcp.server - ✓ Connected

---

Linux • Codex CLI

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Codex

codex mcp add mqtt \
  --env MQTT_HOST=YOUR_BROKER_IP \
  --env MQTT_PORT=1883 \
  --env MQTT_USERNAME=YOUR_USERNAME \
  --env MQTT_PASSWORD=YOUR_PASSWORD \
  -- python3 -m mqtt_mcp.server

Step 3: Verify

codex mcp list

---

Linux • Cursor

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Cursor

Open Cursor Settings → MCP, or create ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-only):

{
  "mcpServers": {
    "mqtt": {
      "command": "python3",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart Cursor

---

Linux • Cline

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Cline

In VS Code, click MCP Servers icon → Configure MCP Servers, or edit cline_mcp_settings.json:

{
  "mcpServers": {
    "mqtt": {
      "command": "python3",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart VS Code

---

Linux • Other Clients

For any MCP client that supports stdio transport:

1. Install the package:

pip install mqtt-mcp-server

2. Configure with these values:

• Command: python3
• Args: ["-m", "mqtt_mcp.server"]
• Environment variables:
  • MQTT_HOST - Your broker IP/hostname
  • MQTT_PORT - Broker port (usually 1883)
  • MQTT_USERNAME - Optional username
  • MQTT_PASSWORD - Optional password

---

macOS

macOS • Claude Code

Step 1: Install the package

pip3 install mqtt-mcp-server

Step 2: Add to Claude Code

claude mcp add --transport stdio mqtt \
  --env MQTT_HOST=YOUR_BROKER_IP \
  --env MQTT_PORT=1883 \
  --env MQTT_USERNAME=YOUR_USERNAME \
  --env MQTT_PASSWORD=YOUR_PASSWORD \
  -- python3 -m mqtt_mcp.server

Step 3: Verify

claude mcp list

You should see: mqtt: python3 -m mqtt_mcp.server - ✓ Connected

---

macOS • Codex CLI

Step 1: Install the package

pip3 install mqtt-mcp-server

Step 2: Add to Codex

codex mcp add mqtt \
  --env MQTT_HOST=YOUR_BROKER_IP \
  --env MQTT_PORT=1883 \
  --env MQTT_USERNAME=YOUR_USERNAME \
  --env MQTT_PASSWORD=YOUR_PASSWORD \
  -- python3 -m mqtt_mcp.server

Step 3: Verify

codex mcp list

---

macOS • Claude Desktop

Step 1: Install the package

pip3 install mqtt-mcp-server

Step 2: Configure Claude Desktop

Open: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mqtt": {
      "command": "python3",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart Claude Desktop

---

macOS • Cursor

Step 1: Install the package

pip3 install mqtt-mcp-server

Step 2: Add to Cursor

Open Cursor Settings → MCP, or create ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-only):

{
  "mcpServers": {
    "mqtt": {
      "command": "python3",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart Cursor

---

macOS • Cline

Step 1: Install the package

pip3 install mqtt-mcp-server

Step 2: Add to Cline

In VS Code, click MCP Servers icon → Configure MCP Servers, or edit cline_mcp_settings.json:

{
  "mcpServers": {
    "mqtt": {
      "command": "python3",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart VS Code

---

macOS • Other Clients

For any MCP client that supports stdio transport:

1. Install the package:

pip3 install mqtt-mcp-server

2. Configure with these values:

• Command: python3
• Args: ["-m", "mqtt_mcp.server"]
• Environment variables:
  • MQTT_HOST - Your broker IP/hostname
  • MQTT_PORT - Broker port (usually 1883)
  • MQTT_USERNAME - Optional username
  • MQTT_PASSWORD - Optional password

---

Windows

Windows • Claude Code

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Claude Code

claude mcp add --transport stdio mqtt `
  --env MQTT_HOST=YOUR_BROKER_IP `
  --env MQTT_PORT=1883 `
  --env MQTT_USERNAME=YOUR_USERNAME `
  --env MQTT_PASSWORD=YOUR_PASSWORD `
  -- python -m mqtt_mcp.server

Step 3: Verify

claude mcp list

You should see: mqtt: python -m mqtt_mcp.server - ✓ Connected

---

Windows • Codex CLI

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Codex

codex mcp add mqtt `
  --env MQTT_HOST=YOUR_BROKER_IP `
  --env MQTT_PORT=1883 `
  --env MQTT_USERNAME=YOUR_USERNAME `
  --env MQTT_PASSWORD=YOUR_PASSWORD `
  -- python -m mqtt_mcp.server

Step 3: Verify

codex mcp list

---

Windows • Claude Desktop

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Configure Claude Desktop

Open: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mqtt": {
      "command": "python",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart Claude Desktop

---

Windows • Cursor

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Cursor

Open Cursor Settings → MCP, or create ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-only):

{
  "mcpServers": {
    "mqtt": {
      "command": "python",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart Cursor

---

Windows • Cline

Step 1: Install the package

pip install mqtt-mcp-server

Step 2: Add to Cline

In VS Code, click MCP Servers icon → Configure MCP Servers, or edit cline_mcp_settings.json:

{
  "mcpServers": {
    "mqtt": {
      "command": "python",
      "args": ["-m", "mqtt_mcp.server"],
      "env": {
        "MQTT_HOST": "YOUR_BROKER_IP",
        "MQTT_PORT": "1883",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "MQTT_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

Step 3: Restart VS Code

---

Windows • Other Clients

For any MCP client that supports stdio transport:

1. Install the package:

pip install mqtt-mcp-server

2. Configure with these values:

• Command: python (not python3)
• Args: ["-m", "mqtt_mcp.server"]
• Environment variables:
  • MQTT_HOST - Your broker IP/hostname
  • MQTT_PORT - Broker port (usually 1883)
  • MQTT_USERNAME - Optional username
  • MQTT_PASSWORD - Optional password

---

Available Tools

After installation, ask your AI assistant: "What MQTT tools are available?"

You should see 4 tools:

topics

Discover MQTT topics on your broker.

Parameters:
- scan_timeout: Scan duration in seconds (1-60, default: 10)
- keywords: Filter topics by keywords
- limit: Max results (1-200, default: 50)

value

Read current values from topics (uses cache for speed).

Parameters:
- topics: List of topic paths (required)
- timeout: Wait time per topic (1-60, default: 5)

publish

Send commands to MQTT devices.

Parameters:
- messages: List of {topic, payload, qos, retain}
- timeout: Network timeout (1-30, default: 3)

record

Monitor MQTT events in real-time.

Parameters:
- timeout: Recording duration (1-300, default: 30)
- topics: Specific topics to monitor
- keywords: Filter by keywords

---

Troubleshooting

"python3 not found" (Windows)

Use 'python' instead of 'python3' in all commands

"Connection refused"

1. Check MQTT broker is running
2. Verify MQTT_HOST and MQTT_PORT are correct
3. Check firewall settings
4. Test connection: mosquitto_sub -h YOUR_HOST -p 1883 -t "#"

"Module not found: mqtt_mcp"

Install the package: pip install mqtt-mcp-server
If using venv, make sure it's activated

Tools not appearing

1. Restart your AI client
2. Check JSON syntax in config file
3. Verify connection: claude mcp list (or codex mcp list)
4. Check logs (location depends on client)

Permission errors (Linux/macOS)

Use pip3 install --user mqtt-mcp-server
Or install in virtual environment

---

Development

For contributors and developers:

Install from source

# Clone repository
git clone https://github.com/eduard256/mqtt-mcp-server.git
cd mqtt-mcp-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Run tests

# Linux/macOS
python3 tests/test_topics.py
python3 tests/test_value.py
python3 tests/test_publish.py
python3 tests/test_record.py

# Windows
python tests\test_topics.py
python tests\test_value.py
python tests\test_publish.py
python tests\test_record.py

Requirements

• Python 3.10+
• MQTT broker (Mosquitto, EMQX, HiveMQ, etc.)

---

Links

• PyPI: https://pypi.org/project/mqtt-mcp-server/
• GitHub: https://github.com/eduard256/mqtt-mcp-server
• Issues: https://github.com/eduard256/mqtt-mcp-server/issues

License

MIT License - See LICENSE for details