messagers — MCP push-notification tool

English | 简体中文

An MCP server that gives any MCP client (Claude Code, etc.) a send_notification tool. The AI calls it to proactively push a short message to your phone — no need to read any doc or remember a curl/token. It is a thin wrapper: the tool just POSTs to the Apprise push gateway; all chat credentials / proxy / channels live in the gateway.

Claude / MCP client ── send_notification(message, title?, tag?) ──► notify_mcp.py
                                                                        │ HTTP POST (+bearer)
                                                                        ▼
                                                  apprise gateway ──► Telegram / Feishu / ...

Point the wrapper at your gateway with NOTIFY_GATEWAY_URL (see Configure). The gateway itself (server + how to deploy it) is documented in docs/NOTIFY_GATEWAY.md; that file describes one example deployment (Linux + systemd) — host, port and proxy will differ per machine.

The tool

send_notification(message: str, title: str = "", tag: str = "default") -> str — pushes message (with optional bold title) to the recipient group tag. Returns "ok" or an error string.

Install

Dependencies are managed with uv (Python 3.12, pinned in .python-version; lockfile uv.lock is committed):

uv sync                    # wrapper deps (mcp) + dev tools (pytest, pre-commit)
uv sync --extra gateway    # also install apprise, for running the gateway locally

Scripts

Script	What it does
scripts/install_mcp.sh	Register this MCP with whichever clients are installed (Claude Code user scope + Codex CLI global). Idempotent.
scripts/start_gateway.sh	Run the Apprise push gateway (server.py) in the foreground, with sensible HOST/PORT defaults.

./scripts/install_mcp.sh      # add the MCP to Claude Code + Codex CLI
./scripts/start_gateway.sh    # start the gateway (needs ./token and ./targets.json)

A real deployment usually runs the gateway under a service manager (e.g. systemd) — see docs/NOTIFY_GATEWAY.md. start_gateway.sh is for local/manual runs.

Configure

Config is via environment variables (the tool reads them at runtime):

Env	Default	Meaning
NOTIFY_GATEWAY_URL	http://localhost:27319/notify	gateway endpoint — set this to your gateway's host:port
NOTIFY_GATEWAY_TOKEN	—	bearer token (overrides the file)
NOTIFY_TOKEN_FILE	./.token next to the script	file holding the bearer token

The default assumes the gateway runs on the same host. On any other machine, set NOTIFY_GATEWAY_URL to where the gateway actually listens (e.g. when registering, ./scripts/install_mcp.sh bakes in NOTIFY_GATEWAY_URL if you export it first).

Put the gateway bearer token in a gitignored .token file (recommended — keeps the secret out of both git and the MCP client config):

printf '%s' '<BEARER_TOKEN>' > .token && chmod 600 .token

Register with Claude Code / Codex CLI

Easiest — from the repo directory, run the install script (it auto-detects the repo path and registers with both clients using a uv run launch command, so the server uses this repo's locked deps):

# optionally point at your gateway first; it gets baked into the registration:
export NOTIFY_GATEWAY_URL=http://<gateway-host>:<port>/notify
./scripts/install_mcp.sh

Or register manually (replace <repo> with this repo's absolute path):

# Claude Code, user scope (available in every project):
claude mcp add notify -s user -- uv run --directory <repo> python notify_mcp.py

# Codex CLI (writes to ~/.codex/config.toml; verify with `codex mcp list`):
codex mcp add notify -- uv run --directory <repo> python notify_mcp.py

Restart / reconnect the client so it picks up the new server. The send_notification tool then appears automatically — the AI reads the tool description, not this README.

To point at a gateway, add -e NOTIFY_GATEWAY_URL=http://<gateway-host>:<port>/notify (Claude) / --env ... (Codex).

Windows: the .sh scripts need Git Bash / WSL. Without them, register manually as above (use where uv to confirm uv is on PATH) and use a native path for <repo>.

Test (without an MCP client)

uv run python -c "from notify_mcp import _post; print(_post('test from notify-mcp', title='hello'))"
# -> (True, '{"ok": true, ...}')  and a chat message arrives

Unit tests

uv run pytest -q    # 28 tests, no network needed

tests/ covers the wrapper (test_notify_mcp.py), the gateway with a stubbed apprise (test_server.py), and the MCP introspection contract (test_introspection.py). None of them touch the real network or gateway.

Lint / format (pre-commit)

Formatting and linting are enforced with ruff via pre-commit; uv-lock keeps uv.lock in sync with pyproject.toml.

uv run pre-commit install        # once per clone — runs the hooks on every commit
uv run pre-commit run --all-files

Docs

All under docs/:

• docs/NOTIFY_GATEWAY.md — example gateway deployment (systemd, proxy, Telegram/Feishu).
• docs/MCP_INTROSPECTION.md — how a client discovers this server's identity and tool (the tool description IS the send_notification docstring; there is no URL path).
• docs/ABOUT.txt — short, human-friendly intro (中文).