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.

Related MCP server: MQTT MCP Server

Environment variables

Required:

Optional:

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:

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