simple-notify

simple-notify-mcp is an MCP server that coordinates text-to-speech (TTS) and Telegram-based notifications through a set of tools. It exposes a status tool to report capabilities and configuration state, optional setup Web UI controls for configuring keys and providers, and a set of actions to perform on task completion or during long-running tasks. Core capabilities include tts_say for speech output, telegram_notify for Telegram alerts, and telegram_read_incoming/telegram_read_media to inspect inbound Telegram messages or media. When setup Web is enabled, you can start a local web UI to configure providers, keys, and chat IDs, and you can stop it when configuration is complete. The tools are designed to be invoked by an agent (Codex, Claude Code, or another MCP client) to orchestrate user-facing notifications during and after tasks.

Prerequisites:

• Node.js and npm (for npx usage)
• Internet access to fetch the MCP server package

Install and run (recommended: agent-managed setup web):

# Remove any existing MCP entry for this server (if present)
codex mcp remove simple-notify

# Add the MCP server with setup-web enabled (recommended for easy reconfiguration)
codex mcp add simple-notify -- \
  npx -y simple-notify-mcp@latest \
  --enable-setup-web

If you prefer minimal runtime without the setup web UI:

codex mcp remove simple-notify
codex mcp add simple-notify -- npx -y simple-notify-mcp@latest

Optional environment variables (pass during add):

codex mcp add simple-notify -- \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env FAL_KEY="$FAL_KEY" \
  -- npx -y simple-notify-mcp@latest \
  --enable-setup-web \
  --setup-port 21420

Optional: to disable the setup web UI later, omit --enable-setup-web or run the stop command via the agent as described in the status output.

For Claude Code users, the same steps apply with their respective tooling, using the same commands inside the Claude context.

Note: This MCP server is invoked via npx and will fetch the latest simple-notify-mcp package. Ensure your environment variables for providers (OPENAI_API_KEY, FAL_KEY) are kept secure.

Tips and notes:

• The tool set includes simple_notify_status (always available), simple_notify_setup_web_start/stop (when --enable-setup-web is used), tts_say (async by default), and Telegram-related tools that require a configured bot token and chat ID.
• If you enable the setup web UI, you will receive a tokenized setup URL via simple_notify_setup_web_start; share this link to configure providers, keys, and chat IDs.
• Telegram formatting supports Markdown and HTML parse modes; ensure content complies with Telegram limits (message 4096 chars, caption 1024 chars). If Telegram formatting fails, the server may retry with plain text.
• To read unread incoming messages or media from Telegram, ensure telegram_read_incoming or telegram_read_media is enabled by configuring the bot token and chat id.
• If you modify provider keys later, you can re-run the setup web to update configuration, or switch back to a minimal runtime and adjust env vars as needed.