Integration with Eclipse Mosquitto public broker for testing MQTT operations such as connect, publish, subscribe, and disconnect.
Integration with HiveMQ public broker for testing MQTT operations such as connect, publish, subscribe, and disconnect.
Provides MQTT client functionality, allowing connections to any MQTT broker, publishing and subscribing to topics, managing subscriptions, and checking connection status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MQTT MCP Server Publish 'hello' to topic 'test'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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!
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
npm install
npm run buildSee FASTMCP_DEPLOYMENT.md for one-click cloud deployment!
Run the automated setup script:
npm run setup # macOS/Linux
npm run setup:windows # WindowsOr 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:
Visit https://fastmcp.cloud
Create a project from this GitHub repository
Set entrypoint to mqtt_mcp_server.py
Deploy with one click!
See FASTMCP_DEPLOYMENT.md for detailed instructions.
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:webThen open your browser to http://localhost:3000
How it works:
The web app connects to the MQTT broker and subscribes to the configured topic (default: color/change)
When any MQTT client publishes a color to that topic, the background changes instantly
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)
npm startConnect 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:1883Publish 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"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.
Unsubscribe from an MQTT topic.
Parameters:
topic (required): The MQTT topic to unsubscribe from
Disconnect from the MQTT broker.
Get the current connection status including active subscriptions.
Start the web application:
npm run start:webOpen your browser to http://localhost:3000
Ask Claude to publish colors (via MCP):
Connect to mqtt://broker.hivemq.com:1883 and publish "red" to topic "color/change"Watch the background change in real-time!
Try different colors:
Publish "#FF5733" to topic "color/change"
Publish "blue" to topic "color/change"
Publish "rgb(46, 204, 113)" to topic "color/change"Connect to a broker:
Connect to the public MQTT broker at mqtt://broker.hivemq.com:1883Subscribe to a topic:
Subscribe to topic "test/demo"Publish a message:
Publish "Hello from Claude!" to topic "test/demo"Check status:
What's the MQTT connection status?Disconnect:
Disconnect from the MQTT brokerFor 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.
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watchMIT
Connect to an MQTT broker
| Name | Required | Description | Default |
|---|---|---|---|
| broker_url | Yes | MQTT broker URL (e.g., mqtt://localhost:1883 or mqtts://broker.example.com:8883) | |
| client_id | No | Optional client ID for the connection | |
| username | No | Optional username for authentication | |
| password | No | Optional password for authentication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behaviors like connection timeout, success/failure handling, or state management. It only says 'Connect to an MQTT broker', leaving many aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a single sentence. While efficient, it may be too minimal for a connection tool; however, it avoids unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in a suite of MQTT tools, the description lacks details about connection lifecycle, return values, and error scenarios. It does not cover the full context needed for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The tool description adds no extra meaning beyond what the schema already provides, achieving the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Connect) and the resource (an MQTT broker), distinguishing it from siblings like mqtt_disconnect or mqtt_publish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool (e.g., before any other MQTT operations) or when not to (e.g., if already connected). No comparison to alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect from the MQTT broker
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. Only states the action without disclosing side effects, idempotency, or connection state requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Perfectly concise for the action described.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, the description is adequate but lacks context on prerequisites, error states, or behavior when already disconnected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% trivially. Per guidelines, baseline is 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'disconnect' and the resource 'MQTT broker'. Distinguishes from sibling tools like mqtt_connect and mqtt_publish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage after a connection is established, but provides no explicit guidance on when to use this tool versus alternatives, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a message to an MQTT topic
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The MQTT topic to publish to | |
| message | Yes | The message payload to publish | |
| qos | No | Quality of Service level (0, 1, or 2). Default is 0 | |
| retain | No | Whether to retain the message on the broker. Default is false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks details about side effects (e.g., requires an active connection, behavior of retain flag). It only states the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant information, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is adequate for a simple tool but omits important context like the need for a prior connection and the effect of the 'retain' parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the description adds no new meaning beyond what the schema already provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (publish) and resource (message to MQTT topic), making it easily distinguishable from sibling tools like mqtt_subscribe or mqtt_connect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to send a message) but offers no explicit guidance on when not to use it or alternatives, which is a missed opportunity for clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current MQTT connection status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal and does not disclose behavioral traits such as latency, caching, authentication requirements, or return value format. With no annotations, the burden is on the description, and it fails to add depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, which is concise and front-loaded. It could be slightly expanded with return details, but the structure is efficient for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose but lacks important context such as what the status looks like (e.g., boolean, object) and whether it is real-time. This gap reduces completeness given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description cannot add meaning beyond the schema. The baseline of 3 is appropriate as it does not need to compensate for missing parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the MQTT connection status, using a specific verb and resource. It is easily distinguishable from sibling tools that perform actions like connecting or publishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. However, the name and sibling list imply it is for checking status, lacking when-not or contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscribe to an MQTT topic to receive messages
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The MQTT topic to subscribe to (supports wildcards: + for single level, # for multi-level) | |
| qos | No | Quality of Service level (0, 1, or 2). Default is 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It only states the basic action but fails to mention persistence of subscription, event handling, or the need for prior connection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too minimal. It does not explain what the agent can expect after subscribing (e.g., message reception) or that a connection must be established first.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description does not add additional meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Subscribe) and the resource (MQTT topic) and the purpose (to receive messages). It effectively distinguishes from sibling tools like mqtt_publish, mqtt_connect, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites like requiring an active connection via mqtt_connect, nor does it indicate when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unsubscribe from an MQTT topic
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The MQTT topic to unsubscribe from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose behavioral traits. It does not indicate if the operation is safe, destructive, or requires establishing a connection first. Minimal information beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose. Every word is necessary, and no extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, single parameter, and no output schema, the description is too brief. It omits important context such as connection requirements, error conditions, and relationship to the wider MQTT lifecycle (e.g., must be connected and subscribed first).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'topic' with a clear description. The tool description adds no additional meaning beyond what the schema already provides, meeting but not exceeding the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unsubscribe from an MQTT topic' clearly states the action (unsubscribe) and resource (MQTT topic). It distinguishes from the sibling tool mqtt_subscribe by using the opposite verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., mqtt_subscribe or mqtt_disconnect). The description does not specify prerequisites like being connected or previously subscribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0mqtt_connectmqtt_disconnectmqtt_publishmqtt_statusmqtt_subscribemqtt_unsubscribeScored across 6 tools
Each tool has a unique purpose (connect, disconnect, publish, status, subscribe, unsubscribe) with no overlap; an agent can easily distinguish between them.
All tool names follow a consistent 'mqtt_verb' pattern in snake_case, making the tool set predictable and easy to navigate.
Six tools cover the core MQTT operations without unnecessary extras; the count is well-scoped for a focused MQTT client server.
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.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Publish and manage existing HTML presentations from an MCP-capable Agent.
Give any MCP-compatible AI assistant a builder for live, hosted web tools and workflows.
Build, deploy, and operate hosted web apps on VibeKit (vibekit.bot) from any MCP client.
