Skip to main content
Glama

MQTT MCP Server

An MCP (Model Context Protocol) server that provides MQTT client functionality. This allows Claude to interact with MQTT brokers - publishing messages, subscribing to topics, and managing connections.

Available in both TypeScript (Node.js) and Python (FastMCP) versions!

Features

  • MCP Server: Connect to MQTT brokers through Claude

  • Web Application: Real-time background color changes via MQTT

  • Dual Implementation: TypeScript (local) + Python (cloud deployment)

  • Connect to MQTT brokers (supports mqtt:// and mqtts://)

  • Publish messages to topics with QoS and retain options

  • Subscribe to topics (including wildcard subscriptions)

  • Unsubscribe from topics

  • Check connection status

  • Disconnect from brokers

  • WebSocket real-time updates

  • Interactive web UI with color presets

  • FastMCP Cloud ready for one-click deployment

Related MCP server: OMNI-MQTT-MCP

Quick Start

TypeScript Version (Local)

npm install
npm run build

Python Version (FastMCP Cloud)

See FASTMCP_DEPLOYMENT.md for one-click cloud deployment!

Usage

As a Claude Desktop MCP Server

Option 1: TypeScript Version (Local - Easy Setup)

Run the automated setup script:

npm run setup  # macOS/Linux
npm run setup:windows  # Windows

Or manually add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mqtt": {
      "command": "node",
      "args": ["/Users/sara/TestAlin/build/index.js"]
    }
  }
}

After adding this configuration, restart Claude Desktop.

Deploy to FastMCP Cloud for cloud-hosted MQTT MCP server:

  1. Visit https://fastmcp.cloud

  2. Create a project from this GitHub repository

  3. Set entrypoint to mqtt_mcp_server.py

  4. Deploy with one click!

See FASTMCP_DEPLOYMENT.md for detailed instructions.

Web Application with Color Changing Background

The web application subscribes to MQTT messages and changes its background color in real-time!

# Start the web server (defaults to port 3000)
npm run start:web

# Or specify custom settings
MQTT_BROKER=mqtt://broker.hivemq.com:1883 MQTT_TOPIC=color/change PORT=3000 npm run start:web

Then open your browser to http://localhost:3000

How it works:

  1. The web app connects to the MQTT broker and subscribes to the configured topic (default: color/change)

  2. When any MQTT client publishes a color to that topic, the background changes instantly

  3. You can test it from the web UI or ask Claude to publish colors via the MCP server

Environment Variables:

  • MQTT_BROKER: MQTT broker URL (default: mqtt://broker.hivemq.com:1883)

  • MQTT_TOPIC: Topic to subscribe to (default: color/change)

  • PORT: Web server port (default: 3000)

MCP Server Standalone

npm start

Available Tools

mqtt_connect

Connect to an MQTT broker.

Parameters:

  • broker_url (required): MQTT broker URL (e.g., mqtt://localhost:1883 or mqtts://broker.hivemq.com:8883)

  • client_id (optional): Client ID for the connection

  • username (optional): Username for authentication

  • password (optional): Password for authentication

Example:

Connect to mqtt://broker.hivemq.com:1883

mqtt_publish

Publish a message to an MQTT topic.

Parameters:

  • topic (required): The MQTT topic to publish to

  • message (required): The message payload

  • qos (optional): Quality of Service level (0, 1, or 2). Default: 0

  • retain (optional): Whether to retain the message. Default: false

Example:

Publish "Hello World" to topic "test/example"

mqtt_subscribe

Subscribe to an MQTT topic to receive messages.

Parameters:

  • topic (required): The MQTT topic (supports + for single-level and # for multi-level wildcards)

  • qos (optional): Quality of Service level (0, 1, or 2). Default: 0

Example:

Subscribe to topic "sensors/#"

Note: Received messages are logged to stderr and will appear in Claude's context.

mqtt_unsubscribe

Unsubscribe from an MQTT topic.

Parameters:

  • topic (required): The MQTT topic to unsubscribe from

mqtt_disconnect

Disconnect from the MQTT broker.

mqtt_status

Get the current connection status including active subscriptions.

Example Workflow

Using the Web App with Claude's MCP Server

  1. Start the web application:

    npm run start:web
  2. Open your browser to http://localhost:3000

  3. Ask Claude to publish colors (via MCP):

    Connect to mqtt://broker.hivemq.com:1883 and publish "red" to topic "color/change"
  4. Watch the background change in real-time!

  5. Try different colors:

    Publish "#FF5733" to topic "color/change"
    Publish "blue" to topic "color/change"
    Publish "rgb(46, 204, 113)" to topic "color/change"

Using the MCP Server Only

  1. Connect to a broker:

    Connect to the public MQTT broker at mqtt://broker.hivemq.com:1883
  2. Subscribe to a topic:

    Subscribe to topic "test/demo"
  3. Publish a message:

    Publish "Hello from Claude!" to topic "test/demo"
  4. Check status:

    What's the MQTT connection status?
  5. Disconnect:

    Disconnect from the MQTT broker

Public Test Brokers

For testing, you can use these public MQTT brokers:

  • mqtt://broker.hivemq.com:1883 (Eclipse Mosquitto)

  • mqtt://broker.hivemq.com:1883 (HiveMQ)

  • mqtt://mqtt.eclipseprojects.io:1883 (Eclipse IoT)

Note: Do not send sensitive data to public brokers.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

License

MIT

Available Tools

6 tools
mqtt_connectB

Connect to an MQTT broker

Inputs: broker_url (required), client_id, username, password.

mqtt_disconnectA

Disconnect from the MQTT broker

Inputs: no named parameters.

mqtt_publishA

Publish a message to an MQTT topic

Inputs: topic (required), message (required), qos, retain.

mqtt_statusB

Get the current MQTT connection status

Inputs: no named parameters.

mqtt_subscribeB

Subscribe to an MQTT topic to receive messages

Inputs: topic (required), qos.

mqtt_unsubscribeB

Unsubscribe from an MQTT topic

Inputs: topic (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a unique purpose (connect, disconnect, publish, status, subscribe, unsubscribe) with no overlap; an agent can easily distinguish between them.

    Naming Consistency5/5

    All tool names follow a consistent 'mqtt_verb' pattern in snake_case, making the tool set predictable and easy to navigate.

    Tool Count5/5

    Six tools cover the core MQTT operations without unnecessary extras; the count is well-scoped for a focused MQTT client server.

    Completeness4/5

    Essential lifecycle operations (connect, disconnect, publish, subscribe, unsubscribe) are present, plus a status check. A tool to fetch received messages might be missing, but this is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to interact with MQTT brokers through publish, subscribe, and query operations. Provides fine-grained topic permissions with wildcard support for secure IoT device communication and sensor data access.
      13 PyPI
      2
      BSD 3-Clause
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to publish and subscribe to MQTT topics with configurable transport options (STDIO, Streamable HTTP, SSE), supporting both local development and web deployments with flexible broker authentication.
      2
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects to a Coreflux MQTT broker and provides tools for managing Coreflux commands (models, actions, rules, routes) and executing MQTT operations through natural language interactions with AI assistants.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to MQTT brokers for smart home automation and IoT device control, enabling topic discovery, sensor reading, command sending, and event monitoring.
      2
      MIT