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 to 1.
• retain — whether to publish as a retained MQTT message, defaults to false.

get_mqtt_config

Returns the configured MQTT target without exposing the password.

Environment variables

Required:

Variable	Description
MQTT_URL	Broker URL. Supports mqtt://, tcp://, mqtts://, and ssl://.
MQTT_TOPIC	Topic to publish all agent messages to.

Optional:

Variable	Description
MQTT_USERNAME	MQTT username. Leave blank for anonymous brokers.
MQTT_PASSWORD	MQTT password. Leave blank for anonymous brokers.
MQTT_KEEPALIVE_SECONDS	MQTT keepalive. Defaults to 30.
MQTT_PUBLISH_TIMEOUT_SECONDS	Publish wait timeout. Defaults to 10.

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 notifymcp

For a fixed version, use a tag or commit:

uvx --from git+https://github.com/mbush91/NotifyMCP@v0.1.0 notifymcp

Run 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:latest

The 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 main as latest and sha-<commit>
• tags like v0.1.0 as semver Docker tags
• manual workflow_dispatch runs

Configure these repository secrets in GitHub before publishing:

Secret	Description
DOCKERHUB_USERNAME	Docker Hub username or organization.
DOCKERHUB_TOKEN	Docker Hub access token.

The image name will be:

DOCKERHUB_USERNAME/notifymcp

Example 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 . notifymcp