pushover-mcp

A tiny MCP server that sends push notifications through Pushover.

It exposes one tool:

• send_notification — send a message with optional title, priority, sound, url, url_title, and device.

Two parameters are designed to read well to an LLM:

• priority uses names instead of numbers: lowest, low, normal (default), high, emergency (repeats until acknowledged).
• sound is an allowlist fetched live from Pushover's sounds API once at startup and cached for the process. If that fetch fails (offline, or no token), it falls back to a baked-in list so the server still starts.

Setup

1. Get your user key from your Pushover dashboard and create an application to get an API token at https://pushover.net/apps/build.

2. Install dependencies:

   uv sync
   

Run

The server reads PUSHOVER_TOKEN and PUSHOVER_USER from the environment.

With 1Password (recommended)

.env holds secret references (op://…), not the secrets themselves. Launch through op run to resolve them at runtime:

op run --env-file=.env -- uv run pushover_mcp.py

With plain env vars

PUSHOVER_TOKEN=... PUSHOVER_USER=... uv run pushover_mcp.py

Use with Claude Code / Claude Desktop

Launching via op run keeps secrets out of the MCP config entirely:

claude mcp add pushover -- \
  op run --env-file=/Users/charlesbine/Documents/prog/mcp/pushover/.env -- \
  uv run --directory /Users/charlesbine/Documents/prog/mcp/pushover pushover_mcp.py

Or as JSON (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "pushover": {
      "command": "op",
      "args": [
        "run", "--env-file=/Users/charlesbine/Documents/prog/mcp/pushover/.env", "--",
        "uv", "run", "--directory", "/Users/charlesbine/Documents/prog/mcp/pushover", "pushover_mcp.py"
      ]
    }
  }
}

Tests

uv run pytest

Tests mock the network and use no real credentials, so they run offline. Run them with plain uv run pytest (not via op run) so the import-time sound fetch falls back instead of calling the live API. GitHub Actions runs the suite on every push and pull request across Python 3.10–3.13 (see .github/workflows/ci.yml).

Run over HTTP (Docker)

The server speaks stdio by default. Set MCP_TRANSPORT=streamable-http to serve over Streamable HTTP instead, so any HTTP-capable MCP client can connect at http://<host>:8000/mcp. The Docker image sets this for you.

docker build -t pushover-mcp .
docker run --rm -e PUSHOVER_TOKEN -e PUSHOVER_USER -p 8000:8000 pushover-mcp

As a Compose service — credentials live in this container's own environment (an env_file or Docker secrets), so they stay isolated to this tool:

services:
  pushover-mcp:
    build: .
    environment:
      PUSHOVER_TOKEN: ${PUSHOVER_TOKEN}
      PUSHOVER_USER: ${PUSHOVER_USER}
    restart: unless-stopped

The HTTP endpoint is unauthenticated, so don't expose it publicly — keep it on a private/internal network (and drop the published ports: if a co-located client reaches it over the Compose network).

License

MIT © Charles Bine