NotifyMCP
NotifyMCP publishes agent messages to a configured MQTT topic and exposes the MQTT target config for use with NotifyMQTT phone notifications.
Publish a message to the configured MQTT topic via the
publish_messageMCP tool.Set MQTT QoS (
0/1/2, default1) and retain flag (defaultfalse) when publishing.Retrieve the configured MQTT target (broker URL and topic) without exposing the password via
get_mqtt_config.Send notifications over HTTP with
POST /notify(or/publish) using anX-API-Keyor Bearer token.Check server health with
GET /healthz.Run as an MCP stdio server, optional HTTP endpoint, or Docker/uvx deployment.
Allows publishing messages to an MQTT broker via the publish_message tool, enabling agents to send notifications or data to MQTT topics.
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., "@NotifyMCP publish a message 'Deployment finished successfully'"
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.
NotifyMCP
NotifyMCP is a small FastMCP server that lets an agent publish messages to a configured MQTT topic.
It is intended to pair with the NotifyMQTT Android app: an agent calls the MCP tool, NotifyMCP publishes to MQTT, and NotifyMQTT turns that MQTT message into a phone notification.
NotifyMCP can run either directly with uvx or as a Docker container pulled from Docker Hub.
Tools
publish_message
Publishes a message to the MQTT topic configured by environment variables.
Arguments:
message— message payload to publish.qos— MQTT QoS level, defaults to1.retain— whether to publish as a retained MQTT message, defaults tofalse.
get_mqtt_config
Returns the configured MQTT target without exposing the password.
Related MCP server: MQTT-Bridge
HTTP endpoint
A simple stdlib-based HTTP endpoint is available alongside (or instead of) the MCP server:
# Generate the hash once and put it in your env file:
python -c "import hashlib; print(hashlib.sha256(b'your-api-key-here').hexdigest())"
export MQTT_URL="mqtt://192.168.1.10:1883"
export MQTT_TOPIC="notify/test"
export NOTIFY_API_KEY_HASH="<sha256 hex of your API key>"
export HTTP_PORT="8080"
# HTTP-only mode:
uv run python -m notifymcp.http_server
# Or run MCP (stdio) + HTTP together:
HTTP_ENABLED=true uv run python -m notifymcp.serverSend a notification:
curl -s -X POST http://localhost:8080/notify \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key-here" \
-d '{"message": "hello from http", "qos": 1, "retain": false}'Notes:
POST /notify(aliasPOST /publish) requires the raw API key in theX-API-Keyheader (Authorization: Bearer <key>also works). Only the SHA-256 hash (NOTIFY_API_KEY_HASH) is stored in the env file; the raw key is never stored server-side.Request body is JSON:
message(required, non-empty string),qos(optional,0/1/2, defaults to1),retain(optional bool, defaults tofalse).GET /healthzreturns{"ok": true}without auth.Responses:
200published,400bad request,401bad/missing key,404unknown path,502MQTT publish failure.
Environment variables
Required:
Variable | Description |
| Broker URL. Supports |
| Topic to publish all agent messages to. |
Optional:
Variable | Description |
| MQTT username. Leave blank for anonymous brokers. |
| MQTT password. Leave blank for anonymous brokers. |
| MQTT keepalive. Defaults to |
| Publish wait timeout. Defaults to |
| Set to |
| HTTP bind address. Defaults to |
| HTTP bind port. Defaults to |
| SHA-256 hex digest of the HTTP API key. Required for HTTP mode. |
mqtt:// and tcp:// default to port 1883. mqtts:// and ssl:// default to port 8883 and enable TLS.
Run with uvx from GitHub
You can run the MCP server directly from the GitHub repo with uvx:
export MQTT_URL="mqtt://192.168.1.10:1883"
export MQTT_USERNAME=""
export MQTT_PASSWORD=""
export MQTT_TOPIC="notify/test"
uvx --from git+https://github.com/mbush91/NotifyMCP notifymcpFor a fixed version, use a tag or commit:
uvx --from git+https://github.com/mbush91/NotifyMCP@v0.1.0 notifymcpRun from Docker Hub
After the Docker Hub publish workflow has run, pull and run the image:
docker pull <dockerhub-username>/notifymcp:latest
docker run --rm -i \
-e MQTT_URL="mqtt://192.168.1.10:1883" \
-e MQTT_USERNAME="" \
-e MQTT_PASSWORD="" \
-e MQTT_TOPIC="notify/test" \
<dockerhub-username>/notifymcp:latestThe container runs the MCP server over stdio, so keep -i when using it from an MCP host.
Docker Hub publishing
The Docker Hub Publish GitHub Actions workflow pushes images on:
pushes to
mainaslatestandsha-<commit>tags like
v0.1.0as semver Docker tagsmanual
workflow_dispatchruns
Configure these repository secrets in GitHub before publishing:
Secret | Description |
| Docker Hub username or organization. |
| Docker Hub access token. |
The image name will be:
DOCKERHUB_USERNAME/notifymcpExample MCP client config: uvx
{
"mcpServers": {
"notifymcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/mbush91/NotifyMCP",
"notifymcp"
],
"env": {
"MQTT_URL": "mqtt://192.168.1.10:1883",
"MQTT_USERNAME": "",
"MQTT_PASSWORD": "",
"MQTT_TOPIC": "notify/test"
}
}
}
}Example MCP client config: Docker
{
"mcpServers": {
"notifymcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MQTT_URL=mqtt://192.168.1.10:1883",
"-e",
"MQTT_USERNAME=",
"-e",
"MQTT_PASSWORD=",
"-e",
"MQTT_TOPIC=notify/test",
"<dockerhub-username>/notifymcp:latest"
]
}
}
}Local development
uv sync --extra dev
uv run ruff check .
uv run pytest
uv build
docker build -t notifymcp:local .You can also smoke-test the local checkout through uvx:
uvx --from . notifymcpAvailable Tools
2 toolsget_mqtt_configA
Return the configured MQTT target, excluding secrets.
Inputs: no named parameters. Returns: object
publish_messageB
Publish a message to the configured MQTT topic.
The broker URL, username, password, and topic are configured through the container environment: MQTT_URL, MQTT_USERNAME, MQTT_PASSWORD, MQTT_TOPIC.
Inputs: message (required), qos, retain. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
publish_message and get_mqtt_config have clearly distinct purposes: one sends a message, the other reads configuration. There is no overlap or ambiguity between the two tools.
Both tools follow a consistent verb_noun pattern: 'publish_message' and 'get_mqtt_config'. The naming is uniformly action-first and predictable.
With only 2 tools, the set is minimal but appropriate for the server's narrow purpose of MQTT notification publishing. It could arguably include a test-connection tool, but the count is reasonable for the scope.
The domain is focused on publishing messages to a configured MQTT topic and checking configuration. Providing both an action and a config inspection covers the essential operations without obvious gaps.
Maintenance
Related MCP Connectors
Let agents send content-free push notifications to a paired phone via MCP.
Authenticated event topics for agent-to-agent messaging with per-agent credentials and audit logs.
Push notifications with personalized sounds - manage and trigger your vybits via MCP
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interacting with MQTT brokers to publish, subscribe, and manage connections, with a real-time web UI for visual feedback.61MIT
- FlicenseNot gradedqualityDmaintenanceProvides MQTT communication capabilities for Large Language Models and other clients, enabling connections to MQTT brokers, publishing and subscribing to topics, and managing real-time messaging workflows.-
- FlicenseNot gradedqualityCmaintenanceEnables agents to send structured notifications to recipients via configurable channels (initial SMTP provider) without exposing delivery addresses or credentials, with tools for listing recipients, listing channels, and sending notifications.-
- AlicenseNot gradedqualityDmaintenanceEnables publishing and retrieving ntfy-style notifications via MCP, supporting topics, titles, tags, priorities, and WebSocket streaming.MIT