ping

# Agent Ping MCP Server A tiny MCP server that gives agents a `ping` tool to send cross-platform desktop notifications when work is done. ## What it does - Exposes one MCP tool: **`ping(message: str, title: str)`** - Sends a native OS notification (Windows toast / macOS alert / Linux notify-send) - Optional **mobile push notifications** via [Apprise](https://github.com/caronc/apprise) — supports 80+ services (ntfy.sh, Pushover, Slack, Discord, Telegram, email, SMS, etc.) - Includes a skill reminding agents to call `ping` before finishing ## Installation **One-liner for any agent:** ```bash curl -fsSL https://raw.githubusercontent.com/gitbannedme/ping/main/install.sh | bash ``` Or pick your agent: ### Claude Code Claude Code reads global MCP servers from `~/.claude.json` (macOS/Linux) or `%USERPROFILE%\.claude.json` (Windows): ```json { "mcpServers": { "agent-ping": { "type": "stdio", "command": "python3", "args": ["/path/to/ping/server.py"] } } } ``` ### Cursor Add to `.cursor/mcp.json`: ```json { "mcpServers": { "agent-ping": { "command": "python3", "args": ["/path/to/ping/server.py"] } } } ``` ### OpenAI Codex CLI Add to `.codex/config.json`: ```json { "mcpServers": { "agent-ping": { "command": "python3", "args": ["/path/to/ping/server.py"] } } } ``` ### OpenCode Tell OpenCode: ``` Fetch and follow instructions from https://raw.githubusercontent.com/gitbannedme/ping/main/.opencode/INSTALL.md ``` ### Manual ```bash git clone https://github.com/gitbannedme/ping.git cd ping pip install -r requirements.txt python server.py ``` ## Mobile Notifications (Optional) Agent-ping uses [Apprise](https://github.com/caronc/apprise) to push notifications to virtually any service. Pick your backend, grab the URL, and set the environment variable before starting your agent. ### Quick start ```bash # Bash / Zsh export APPRISE_URLS="ntfys://my-secret-topic" # Windows PowerShell $env:APPRISE_URLS="ntfys://my-secret-topic" ``` ### Popular backends | Service | Example URL | Notes | |---------|-------------|-------| | [ntfy.sh](https://ntfy.sh) | `ntfys://your-topic` | Simplest — no account needed | | [Pushover](https://pushover.net) | `pover://user@token` | Encrypted, private | | Slack | `slack://TokenA/TokenB/TokenC/Channel` | Team alerts | | Discord | `discord://webhook_id/webhook_token` | Server alerts | | Telegram | `tgram://bottoken/ChatID` | Direct message | | Email | `mailto://user:pass@gmail.com` | Any SMTP server | | SMS | `twilio://AccountSid:AuthToken@FromPhoneNo/ToPhoneNo` | Via Twilio | You can chain multiple services: ```bash export APPRISE_URLS="ntfys://topic pover://user@token discord://id/token" ``` ### Legacy env vars (still work) If you already set these, they auto-convert to apprise URLs: - `NTFY_TOPIC` → `ntfys://<topic>` - `PUSHOVER_TOKEN` + `PUSHOVER_USER` → `pover://<user>@<token>` ## Usage Agents call: ```json { "tool": "ping", "arguments": { "message": "Refactor complete — all tests passing", "title": "Kwillo Backend" } } ``` You get a native desktop notification plus any mobile/remote services you configured.