Allows an AI client to discover industrial edge nodes and devices, monitor real-time metrics, and send commands over MQTT using the Sparkplug B specification.
Also known as nagarjunr/iot-mcp-servers, sparkplug-b, sparkplug-b-mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 83
- Latest version
- 0.1.0
- Last commit
- Oct 31, 2026
- License
- MIT
What is Sparkplug B MCP?
Sparkplug B allows an AI client to discover industrial edge nodes and devices, monitor real-time metrics, and send commands over MQTT using the Sparkplug B specification.
Summary generated from the project's README
About Sparkplug B MCP server
Monitoring industrial edge nodes and controlling SCADA devices from an AI client is what this server enables. It functions as a Primary Host Application by connecting to any MQTT broker that follows the Sparkplug B specification. Users can discover hardware through birth messages, track real-time metrics, and issue commands to specific nodes or devices using the standard protocol.
To use this server, you must configure environment variables including the MQTT host and a unique host ID. It supports various data types such as integers, floats, booleans, and datetime strings. The server also features a session-based watching mechanism, allowing you to buffer and drain decoded traffic through tools like start_watch and get_events rather than relying on a standard request/response pattern.
Developers can manage industrial infrastructure by listing edge nodes, retrieving device metrics, or sending NCMD and DCMD commands. It provides specialized functions like request_node_rebirth to force nodes to republish their state, making it a functional replacement for a traditional historian or SCADA host in an automated workflow.
What you can do with it
- 1Monitor real-time telemetryRetrieve the most recent metric values for a specific device or edge node.
- 2Execute remote commandsWrite new values to metrics on a node or device to control industrial processes.
- 3Track continuous data streamsBuffer and inspect a sequence of decoded Sparkplug messages using a session ID.
Written from the project's README. Every use case is checked against a quote from it.
How to install Sparkplug B MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Sparkplug B MCP in Claude Code
$ claude mcp add --env 'SPARKPLUG_HOST_ID=<SPARKPLUG_HOST_ID>' --env 'SPARKPLUG_MQTT_HOST=<SPARKPLUG_MQTT_HOST>' --env 'SPARKPLUG_MQTT_PASSWORD=<YOUR_SPARKPLUG_MQTT_PASSWORD>' sparkplug-b -- uvx sparkplug-b-mcp-serverInstall Sparkplug B MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sparkplug-b": {
"command": "uvx",
"args": [
"sparkplug-b-mcp-server"
],
"env": {
"SPARKPLUG_HOST_ID": "<SPARKPLUG_HOST_ID>",
"SPARKPLUG_MQTT_HOST": "<SPARKPLUG_MQTT_HOST>",
"SPARKPLUG_MQTT_PASSWORD": "<YOUR_SPARKPLUG_MQTT_PASSWORD>"
}
}
}
}Install Sparkplug B MCP in VS Code
.vscode/mcp.json
{
"servers": {
"sparkplug-b": {
"type": "stdio",
"command": "uvx",
"args": [
"sparkplug-b-mcp-server"
],
"env": {
"SPARKPLUG_HOST_ID": "<SPARKPLUG_HOST_ID>",
"SPARKPLUG_MQTT_HOST": "<SPARKPLUG_MQTT_HOST>",
"SPARKPLUG_MQTT_PASSWORD": "<YOUR_SPARKPLUG_MQTT_PASSWORD>"
}
}
}
}Install Sparkplug B MCP in VS Code CLI
$ code --add-mcp '{"name":"sparkplug-b","type":"stdio","command":"uvx","args":["sparkplug-b-mcp-server"],"env":{"SPARKPLUG_HOST_ID":"<SPARKPLUG_HOST_ID>","SPARKPLUG_MQTT_HOST":"<SPARKPLUG_MQTT_HOST>","SPARKPLUG_MQTT_PASSWORD":"<YOUR_SPARKPLUG_MQTT_PASSWORD>"}}'Install Sparkplug B MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"sparkplug-b": {
"command": "uvx",
"args": [
"sparkplug-b-mcp-server"
],
"env": {
"SPARKPLUG_HOST_ID": "<SPARKPLUG_HOST_ID>",
"SPARKPLUG_MQTT_HOST": "<SPARKPLUG_MQTT_HOST>",
"SPARKPLUG_MQTT_PASSWORD": "<YOUR_SPARKPLUG_MQTT_PASSWORD>"
}
}
}
}Install Sparkplug B MCP in Codex
$ codex mcp add sparkplug-b --env 'SPARKPLUG_HOST_ID=<SPARKPLUG_HOST_ID>' --env 'SPARKPLUG_MQTT_HOST=<SPARKPLUG_MQTT_HOST>' --env 'SPARKPLUG_MQTT_PASSWORD=<YOUR_SPARKPLUG_MQTT_PASSWORD>' -- uvx sparkplug-b-mcp-serverInstall Sparkplug B MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.sparkplug-b] command = "uvx" args = ["sparkplug-b-mcp-server"] [mcp_servers.sparkplug-b.env] SPARKPLUG_HOST_ID = "<SPARKPLUG_HOST_ID>" SPARKPLUG_MQTT_HOST = "<SPARKPLUG_MQTT_HOST>" SPARKPLUG_MQTT_PASSWORD = "<YOUR_SPARKPLUG_MQTT_PASSWORD>"
Install Sparkplug B MCP in Gemini CLI
$ gemini mcp add -s user -e 'SPARKPLUG_HOST_ID=<SPARKPLUG_HOST_ID>' -e 'SPARKPLUG_MQTT_HOST=<SPARKPLUG_MQTT_HOST>' -e 'SPARKPLUG_MQTT_PASSWORD=<YOUR_SPARKPLUG_MQTT_PASSWORD>' sparkplug-b uvx -- sparkplug-b-mcp-serverInstall Sparkplug B MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sparkplug-b": {
"command": "uvx",
"args": [
"sparkplug-b-mcp-server"
],
"env": {
"SPARKPLUG_HOST_ID": "<SPARKPLUG_HOST_ID>",
"SPARKPLUG_MQTT_HOST": "<SPARKPLUG_MQTT_HOST>",
"SPARKPLUG_MQTT_PASSWORD": "<YOUR_SPARKPLUG_MQTT_PASSWORD>"
}
}
}
}Configuration
SPARKPLUG_HOST_IDRequiredThis connector's Sparkplug Host Application ID (used in the spBv1.0/STATE/{id} topic).
SPARKPLUG_MQTT_HOSTRequiredMQTT broker hostname or IP.
SPARKPLUG_MQTT_PASSWORDSecretBroker password, if required
SPARKPLUG_GROUP_IDRestrict discovery/watching to a single Sparkplug Group ID; omit to subscribe to every group
SPARKPLUG_MQTT_PORTMQTT broker port, default 1883
SPARKPLUG_MQTT_USERNAMEBroker username, if required
SPARKPLUG_MQTT_USE_TLStrue/false, default false
| Name | Description | |
|---|---|---|
| SPARKPLUG_HOST_ID | This connector's Sparkplug Host Application ID (used in the spBv1.0/STATE/{id} topic). | Required |
| SPARKPLUG_MQTT_HOST | MQTT broker hostname or IP. | Required |
| SPARKPLUG_MQTT_PASSWORD | Broker password, if required | Secret |
| SPARKPLUG_GROUP_ID | Restrict discovery/watching to a single Sparkplug Group ID; omit to subscribe to every group | |
| SPARKPLUG_MQTT_PORT | MQTT broker port, default 1883 | |
| SPARKPLUG_MQTT_USERNAME | Broker username, if required | |
| SPARKPLUG_MQTT_USE_TLS | true/false, default false |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenagarjunr/iot-mcp-servers is public and reachablegithub.com/nagarjunr/iot-mcp-servers ↗Pass
- Package names this repository as its sourcesparkplug-b-mcp-server names nagarjunr/iot-mcp-servers as sourcepypi.org/project/sparkplug-b-mcp-server/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/nagarjunr/iot-mcp-servers ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from sparkplug-b-mcp-serverPass
- No critical advisory in the package or its dependencies66 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSparkplug B MCP Server
A Model Context Protocol (MCP) server for Sparkplug B — the Eclipse-standard MQTT topic/payload convention for industrial/SCADA data (birth/death certificates, sequenced metrics, protobuf payloads). Works against any MQTT broker that carries Sparkplug B traffic; only the open Sparkplug B specification is used, no vendor-specific extensions.
This server acts as a Sparkplug B Primary Host Application: it subscribes to the entire spBv1.0 namespace, discovers Edge Nodes and Devices from their NBIRTH/DBIRTH messages, tracks their live metrics, and can send them commands (NCMD/DCMD) — the same role a SCADA/historian host application plays in a real deployment.
Built with FastMCP and pysparkplug (itself built on paho-mqtt).
Tools
| Tool | Description |
|---|---|
get_connection_status() |
Report the broker connection and this host application's identity. |
set_host_online(online) |
Publish this connector's own retained Sparkplug STATE message. |
list_edge_nodes(group_id?) |
List Edge Nodes discovered via NBIRTH/NDEATH. |
list_devices(group_id?, edge_node_id?) |
List Devices discovered via DBIRTH/DDEATH. |
get_node_metrics(group_id, edge_node_id) |
Latest known metric values for an Edge Node. |
get_device_metrics(group_id, edge_node_id, device_id) |
Latest known metric values for a Device. |
send_node_command(group_id, edge_node_id, metrics) |
Send an NCMD — write one or more of a node's metrics. |
send_device_command(group_id, edge_node_id, device_id, metrics) |
Send a DCMD — write one or more of a device's metrics. |
request_node_rebirth(group_id, edge_node_id) |
Standard Node Control/Rebirth command — asks a node to republish its full NBIRTH. |
start_watch(group_id?, edge_node_id?, device_id?, message_types?) |
Start buffering decoded Sparkplug traffic matching an optional filter. Returns a session_id. |
get_events(session_id, max_events, timeout_seconds) |
Drain buffered events from a watch session; can wait briefly for one to arrive. |
stop_watch(session_id) |
Stop a watch session and discard its buffered events. |
list_watches() |
List all active watch sessions. |
Why watching is session-based
Like the MQTT wire protocol underneath it, Sparkplug B is a continuous stream, not a request/response API — a single MCP tool call can't "wait forever" for the next birth or data message. start_watch registers an optional filter (group/node/device/message-type) and buffers matching decoded messages in the background (this connector is always subscribed to the whole spBv1.0 namespace, so no extra broker subscription is needed per watch); get_events drains that buffer, optionally waiting a bounded amount of time for new data. Call stop_watch when done.
Supported metric datatypes
INT8/INT16/INT32/INT64, UINT8/UINT16/UINT32/UINT64, FLOAT, DOUBLE, BOOLEAN, STRING, TEXT, UUID, DATETIME, BYTES, FILE, and their *_ARRAY variants. DATASET, TEMPLATE, PROPERTYSET, and PROPERTYSETLIST are part of the Sparkplug B spec but unsupported by the underlying pysparkplug codec, so they're rejected with a clear error rather than silently mishandled.
For send_node_command/send_device_command, value shape depends on datatype: plain int/float/bool/str for scalars, an ISO 8601 string for DATETIME, a base64 string for BYTES/FILE, and a JSON list for *_ARRAY types.
Configuration
| Env var | Required | Description |
|---|---|---|
SPARKPLUG_MQTT_HOST |
Yes | Broker hostname or IP. |
SPARKPLUG_HOST_ID |
Yes | This connector's Sparkplug Host Application ID (used in the spBv1.0/STATE/{id} topic). |
SPARKPLUG_MQTT_PORT |
No | Default 1883. |
SPARKPLUG_MQTT_USERNAME / SPARKPLUG_MQTT_PASSWORD |
No | Broker credentials. |
SPARKPLUG_MQTT_CLIENT_ID |
No | Defaults to a broker-assigned ID. |
SPARKPLUG_MQTT_KEEPALIVE |
No | Seconds, default 60. |
SPARKPLUG_MQTT_CONNECT_TIMEOUT |
No | Seconds to wait for the initial connect, default 10. |
SPARKPLUG_MQTT_USE_TLS |
No | true/false, default false. |
SPARKPLUG_MQTT_TLS_CA_CERTS |
No | Path to a CA bundle. Omit to use the system trust store. |
SPARKPLUG_MQTT_TLS_CLIENT_CERT / SPARKPLUG_MQTT_TLS_CLIENT_KEY |
No | For mutual TLS. |
SPARKPLUG_GROUP_ID |
No | Restrict discovery/watching to a single Sparkplug Group ID. Omit to subscribe to every group (spBv1.0/#). |
Running locally
uv sync
export SPARKPLUG_MQTT_HOST=localhost
export SPARKPLUG_MQTT_PORT=1883
export SPARKPLUG_HOST_ID=my-mcp-host
uv run sparkplugbmcpserver.py
See mcp.json for ready-to-use client configs (stdio and Docker).
Testing against a real broker
This repo's design principles call for testing against a real instance rather than mocks. docker-compose.yml spins up Eclipse Mosquitto (2.x) with an anonymous listener for local testing. Test fixtures use pysparkplug's own EdgeNode/Device classes to act as real simulated PLCs/devices — publishing genuine NBIRTH/DBIRTH/NDATA/DDATA/NDEATH messages and receiving genuine NCMD/DCMD commands over the wire — so coverage is protocol-level, not hand-rolled mocks. Only the "physical" node/device is simulated, since no free real PLC/edge-node hardware exists to test against; the Sparkplug B protocol handling on both sides is real.
docker compose up -d # start Mosquitto on localhost:1883 (anonymous, local testing only)
uv run pytest -v # tests/conftest.py also starts/stops the stack automatically
docker compose down # stop it manually if you started it yourself
License notes
docker-compose.yml and the files under docker/ configure the open-source Eclipse Mosquitto broker (EPL-2.0) for local testing only — they are not part of the MCP server itself.
Sparkplug B MCP questions
How do I add Sparkplug B MCP to Claude Code?
Run claude mcp add --env 'SPARKPLUG_HOST_ID=<SPARKPLUG_HOST_ID>' --env 'SPARKPLUG_MQTT_HOST=<SPARKPLUG_MQTT_HOST>' --env 'SPARKPLUG_MQTT_PASSWORD=<YOUR_SPARKPLUG_MQTT_PASSWORD>' sparkplug-b -- uvx sparkplug-b-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Sparkplug B MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I use this with any MQTT broker?
Yes, it works against any MQTT broker that carries Sparkplug B traffic using the open specification without vendor-specific extensions.
How does the server handle continuous data streams since MCP is request/response?
The server uses a session-based watching mechanism where start_watch buffers decoded traffic in the background, and get_events allows the client to drain that buffer.
What metric data types are supported?
It supports various integer, float, boolean, string, datetime, and byte types, including their array variants.