Allows subscribing to MQTT topics, reading buffered messages, unsubscribing, and listing active subscriptions via an MQTT broker.
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 Read the latest messages from sensors/temperature"
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 enables Cursor to read messages from an MQTT broker.
Subscribe to MQTT topics (supports wildcards + and #)
Read buffered messages from subscribed topics
List active subscriptions
Configurable message buffer size
Related MCP server: OMNI-MQTT-MCP
Install dependencies:
npm installBuild the project:
npm run buildCopy .env.example to .env and configure your MQTT broker settings:
cp .env.example .envEdit the .env file with your MQTT broker details:
Variable | Description | Default |
| MQTT broker URL (mqtt:// or mqtts://) |
|
| Username for authentication | (none) |
| Password for authentication | (none) |
| Client ID for MQTT connection |
|
| Max messages to buffer per topic |
|
Add this MCP server to your Cursor settings (.cursor/mcp.json or global settings):
{
"mcpServers": {
"mqtt": {
"command": "node",
"args": ["C:/path/to/mqtt-mcp/dist/index.js"],
"env": {
"MQTT_BROKER_URL": "mqtt://your-broker:1883",
"MQTT_USERNAME": "your_username",
"MQTT_PASSWORD": "your_password"
}
}
}
}Alternatively, if using a .env file in the project directory:
{
"mcpServers": {
"mqtt": {
"command": "node",
"args": ["C:/path/to/mqtt-mcp/dist/index.js"],
"cwd": "C:/path/to/mqtt-mcp"
}
}
}Subscribe to an MQTT topic to start receiving messages.
Parameters:
topic (required): The MQTT topic to subscribe to
qos (optional): Quality of Service level (0, 1, or 2). Default: 0
Example:
Subscribe to "sensors/temperature"
Subscribe to "devices/+/status" (single-level wildcard)
Subscribe to "home/#" (multi-level wildcard)Unsubscribe from an MQTT topic.
Parameters:
topic (required): The MQTT topic to unsubscribe from
Read buffered messages from subscribed topics.
Parameters:
topic (optional): Specific topic to read from. If omitted, reads from all topics
limit (optional): Maximum messages to return. Default: 10
clear (optional): Clear buffer after reading. Default: false
List all active subscriptions and their message counts.
Parameters: None
First, subscribe to a topic:
"Subscribe to the MQTT topic sensors/temperature"
Wait for messages to arrive, then read them:
"Read the latest messages from sensors/temperature"
Check all active subscriptions:
"List my MQTT subscriptions"
Unsubscribe when done:
"Unsubscribe from sensors/temperature"
MIT
List all active MQTT topic subscriptions and their message counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It mentions 'active' and 'message counts' but says nothing about whether counts are per-topic cumulative or recent, whether the list is paginated, what happens with zero subscriptions, or connection/auth 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, front-loaded with the verb and resource, no redundant or filler text. Every word contributes to scope.
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?
For a zero-parameter list tool with no annotations and no output schema, the description conveys the core purpose but omits return shape, count semantics, and filtering/ordering behavior. Adequate but with clear gaps.
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?
Parameter count is 0, so there are no parameters to document; baseline is 4. The description adds no parameter noise, appropriately matching the empty schema.
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?
States a clear verb (list) and resource (MQTT topic subscriptions) with additional scope (active, message counts). It is distinguishable from mqtt_subscribe/mqtt_unsubscribe by implication, but does not explicitly differentiate from siblings like mqtt_read_messages.
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 versus alternatives like mqtt_read_messages (which might also surface messages) or when subscriptions become inactive. Usage is only implied by the verb.
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. Useful for sending test data or triggering actions on the broker.
| Name | Required | Description | Default |
|---|---|---|---|
| qos | No | Quality of Service level (0, 1, or 2). Default is 0. | |
| topic | Yes | The MQTT topic to publish to (e.g., 'agents/test/status') | |
| retain | No | Whether to set the retain flag on the message. Default is false. | |
| message | Yes | The message payload to publish |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and largely fails it: it says nothing about delivery guarantees, connection/broker prerequisites, error behavior on failure, or whether the call blocks. The only behavioral hints (QoS, retain) live in the schema, not the description.
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?
Two short sentences, the action front-loaded and the rationale second. No redundancy, no filler, immediately scannable.
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?
For a 4-parameter publish tool with no annotations and no output schema, the description is minimally sufficient on the 'what' but silent on operational context an agent would want (required connection state, failure modes, whether a response is returned).
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%, so topic, message, qos, and retain are already fully documented with types, defaults, and an example. The description adds no semantic detail beyond the schema, which is the baseline expectation.
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?
States a specific verb and resource ('Publish a message to an MQTT topic'), which is unmistakably distinct from the subscribe/read/list siblings. It does not, however, explicitly name or contrast itself with any sibling tool.
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 second sentence gives a use context ('sending test data or triggering actions on the broker'), which implies when the tool is appropriate. There is no explicit when-not guidance or reference to alternatives such as mqtt_subscribe for consuming messages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read buffered messages from a subscribed topic. Returns the most recent messages received since subscribing. Supports MQTT wildcards: '+' for single level, '#' for multi-level (e.g., 'sensors/#' returns messages from all topics under 'sensors/').
| Name | Required | Description | Default |
|---|---|---|---|
| clear | No | Whether to clear the message buffer after reading. Default is false. | |
| limit | No | Maximum number of messages to return. Default is 10. Set to 0 or omit to return all messages. | |
| topic | No | The MQTT topic to read messages from. Supports wildcards (+, #) to read from multiple matching topics. If not provided, returns messages from all subscribed topics. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose useful behavior: buffered (not live) retrieval, most-recent-first ordering, and wildcard expansion. It omits buffer capacity, eviction/retention behavior, and whether reads are non-destructive by default (that detail lives only in the schema's 'clear' param).
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?
Three tight sentences: core action first, then return semantics, then the wildcard capability. Zero filler and the most important fact leads.
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?
For a read tool with no annotations and no output schema, the description stops short of what an agent needs: the structure of a returned message (topic, payload, timestamp) and the ordering of the returned array are unspecified. Buffer semantics are covered, but the response contract is not.
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%, so the schema already documents all three parameters including wildcard support and the clear/limit defaults. The description's wildcard sentence largely restates the topic schema description and adds no format or edge-case detail beyond it, so baseline 3 applies.
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 names a specific verb and resource ('Read buffered messages from a subscribed topic') and characterizes the return set ('most recent messages received since subscribing'), which separates it functionally from siblings like mqtt_list_subscriptions. It never names a sibling to actively steer selection, so it falls short of a 5.
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?
Usage is only implied: 'from a subscribed topic' and 'since subscribing' suggest a subscription must already exist, and reading buffered history implies this is the retrieval step after mqtt_subscribe. There is no explicit when-to-use/when-not statement and no guidance on choosing this over mqtt_list_subscriptions.
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 start receiving messages. Supports MQTT wildcards: '+' for single level, '#' for multi-level.
| Name | Required | Description | Default |
|---|---|---|---|
| qos | No | Quality of Service level (0, 1, or 2). Default is 0. | |
| topic | Yes | The MQTT topic to subscribe to (e.g., 'sensors/temperature' or 'sensors/+/status') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it only adds the wildcard syntax rule. It says nothing about subscription persistence, whether re-subscribing to the same topic replaces or duplicates, error behavior for invalid topics, or required broker/auth state.
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?
Two tight sentences with the core action front-loaded and the wildcard syntax as supporting detail. Every sentence earns its place with no filler.
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?
For a two-parameter tool with a fully documented schema and no output schema, the description covers the essentials, but with zero annotations it omits subscription lifecycle behavior (persistence, duplicate subscriptions, error handling) that an agent would need to call 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 description coverage is 100%, so both parameters are already documented, which sets the baseline at 3. The description adds real meaning for the topic parameter by defining '+' as single-level and '#' as multi-level wildcards, but it says nothing about qos beyond what the schema enum already provides.
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 states a specific verb (subscribe) and resource (MQTT topic) and explains the outcome ('start receiving messages'), so the operation is unambiguous. It does not explicitly differentiate itself from siblings such as mqtt_read_messages or mqtt_list_subscriptions, but the verb alone makes the distinction reasonably clear.
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?
Usage is implied by 'to start receiving messages', which hints at the subscribe-then-receive workflow, but there is no explicit statement of when to subscribe versus use mqtt_read_messages or mqtt_list_subscriptions, nor any prerequisites or exclusions.
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 to stop receiving messages.
| 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?
No annotations are provided, so the description carries the full burden and it is thin. It notes that unsubscribing stops receiving messages, but says nothing about scope (per-client vs. global), behavior if the topic was never subscribed, error handling, or whether the unsubscribe is durable across reconnects.
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?
One short sentence, front-loaded with the action and outcome, with no filler. It is efficient but almost too terse to be considered polished structure.
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?
For a single-parameter tool with no output schema and no annotations, the description is minimally sufficient but omits error conditions and operational scope. An agent could call it, but with no guidance on edge cases.
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 is a single parameter with 100% schema description coverage ('The MQTT topic to unsubscribe from'), so the schema already does the work and the description adds nothing further about topic format or wildcard handling. Baseline 3 applies.
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?
States a specific verb (unsubscribe) and resource (MQTT topic) with the effect (stop receiving messages), which clearly separates it from mqtt_subscribe and mqtt_publish. It does not, however, explicitly name or contrast a sibling, so it stops short of the top band.
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?
Usage is only implied: an agent can infer that this reverses a subscription, but there is no statement of when to call it, when not to, or how it relates to mqtt_list_subscriptions or mqtt_read_messages. Adequate but with a clear gap.
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_list_subscriptionsmqtt_publishmqtt_read_messagesmqtt_subscribemqtt_unsubscribeScored across 5 tools
Each tool targets a distinct MQTT operation: subscribe, unsubscribe, publish, read buffered messages, and list active subscriptions. The read and list tools are clearly separated by their descriptions, and no two tools appear to do the same thing.
All tool names use the mqtt_ prefix and snake_case, which is highly consistent. The only minor deviation is that some names include an explicit object (read_messages, list_subscriptions) while others rely on implicit context (subscribe, unsubscribe, publish), but the pattern remains predictable.
Five tools is well-scoped for an MQTT interaction server, covering the essential subscribe, unsubscribe, publish, read, and list operations without unnecessary bloat. Each tool earns its place and the set feels complete for typical messaging tasks.
The core MQTT lifecycle is covered: subscribe, unsubscribe, publish, read buffered messages, and list subscriptions. Minor gaps exist, such as no explicit tool to clear buffered messages or manage connection state, but these are workaround-able or handled outside the tool surface.
Authenticated event topics for agent-to-agent messaging with per-agent credentials and audit logs.
The stock market, in SQL — scan, replay, or subscribe across ~12k US tickers and top 100 cryptos.
Enable interaction with Slack workspaces. Supports subscribing to Slack events through Resources.
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
