Pushover MCP

An MCP server that lets AI agents send push notifications to your phone and desktop through Pushover.

• Rich notifications: title, link, sound, device, HTML or monospace text, image attachments
• Emergency alerts: repeat until acknowledged, then check or cancel them
• Self-correcting: clear tool errors the agent can act on
• stdio or HTTP: runs locally by default, or as a shared HTTP server

Quick start

1. Get two keys from Pushover:
   • User key: shown on your dashboard.
   • App token: create an application.
2. Add the server to your client (below), replacing YOUR_TOKEN and YOUR_USER_KEY.
3. Ask your agent to send you a notification.

Requires Node.js 22 or later.

Setup

Claude Code

claude mcp add pushover -e PUSHOVER_TOKEN=YOUR_TOKEN -e PUSHOVER_USER=YOUR_USER_KEY -- npx -y pushover-mcp@latest

OpenAI Codex

codex mcp add pushover --env PUSHOVER_TOKEN=YOUR_TOKEN --env PUSHOVER_USER=YOUR_USER_KEY -- npx -y pushover-mcp@latest

Claude Desktop, Cursor, Cline

Add this to your client's MCP config file:

{
  "mcpServers": {
    "pushover": {
      "command": "npx",
      "args": ["-y", "pushover-mcp@latest"],
      "env": {
        "PUSHOVER_TOKEN": "YOUR_TOKEN",
        "PUSHOVER_USER": "YOUR_USER_KEY"
      }
    }
  }
}

| Client | Where to find it | | --- | --- | | Claude Desktop | Settings → Developer → Edit Config | | Cursor | ~/.cursor/mcp.json, or .cursor/mcp.json in a project | | Cline | MCP Servers → Configure MCP Servers |

VS Code

Add .vscode/mcp.json. VS Code prompts for the keys once and stores them securely:

{
  "inputs": [
    { "type": "promptString", "id": "pushover-token", "description": "Pushover app token", "password": true },
    { "type": "promptString", "id": "pushover-user", "description": "Pushover user key", "password": true }
  ],
  "servers": {
    "pushover": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pushover-mcp@latest"],
      "env": {
        "PUSHOVER_TOKEN": "${input:pushover-token}",
        "PUSHOVER_USER": "${input:pushover-user}"
      }
    }
  }
}

Zed

Add this to your Zed settings.json, or use Settings → AI → MCP Servers → Add Local Server:

{
  "context_servers": {
    "pushover": {
      "command": "npx",
      "args": ["-y", "pushover-mcp@latest"],
      "env": {
        "PUSHOVER_TOKEN": "YOUR_TOKEN",
        "PUSHOVER_USER": "YOUR_USER_KEY"
      }
    }
  }
}

Tools

| Tool | What it does | | --- | --- | | send_notification | Send a notification. Returns a receipt for emergency notifications. | | get_receipt | Check whether an emergency notification was acknowledged. | | cancel_emergency | Stop an emergency notification from repeating, by receipt or tag. | | list_sounds | List available sounds, including your custom ones. | | validate_user | Check your user key and list your device names. | | get_limits | Show your monthly message quota and how much is left. |

send_notification parameters

Only message is required.

| Parameter | Description | | --- | --- | | message | Notification body, up to 1024 characters. | | title | Defaults to your Pushover app's name. | | priority | -2 silent, -1 quiet, 0 normal, 1 high, 2 emergency. | | sound | Sound name from list_sounds. | | device | Device name to target; join several with commas. Defaults to the configured default device, or all devices. | | url, url_title | A link, and an optional label for it. | | html | Render <b>, <i>, <u>, <font color> and <a href>. | | monospace | Render in a monospace font. Can't be combined with html. | | ttl | Seconds until the notification is deleted from devices. Ignored for emergency (priority 2). | | timestamp | ISO 8601 time to show instead of the time it was received. | | attachment_path | Local image to attach (jpg, png, gif, webp, heic), up to 5 MB. stdio only. | | attachment_base64, attachment_type | Base64 image data and its MIME type. | | retry, expire | Emergency only. Seconds between repeats (default 60, min 30) and until they stop (default 3600, max 10800). | | callback | Emergency only. URL Pushover calls when you acknowledge. | | tags | Emergency only. Labels for cancelling with cancel_emergency. |

Configuration

Set options as environment variables or command-line flags. Flags win, but anyone on the machine can see them in process listings, so prefer environment variables for secrets.

| Environment variable | Flag | Description | | --- | --- | --- | | PUSHOVER_TOKEN | --token | Required. App API token. | | PUSHOVER_USER | --user | Required. User or group key. | | PUSHOVER_DEFAULT_DEVICE | --default-device | Device to use when a call doesn't name one. | | PUSHOVER_DEFAULT_SOUND | --default-sound | Sound to use when a call doesn't name one. | | PUSHOVER_DEFAULT_PRIORITY | --default-priority | Priority to use when a call doesn't set one: -2 to 1. | | PUSHOVER_MCP_TRANSPORT | --transport | stdio (default) or http. | | PUSHOVER_MCP_HOST | --host | HTTP bind address. Default 127.0.0.1. | | PUSHOVER_MCP_PORT or PORT | --port | HTTP port. Default 3000. | | PUSHOVER_MCP_AUTH_TOKEN | --auth-token | Bearer token HTTP clients must send. |

Run npx pushover-mcp --help for the full list.

HTTP mode

By default each client starts its own server over stdio. HTTP mode instead runs one long-lived server that clients connect to by URL. Use it for hosted platforms or sharing one server between clients.

PUSHOVER_TOKEN=... PUSHOVER_USER=... npx pushover-mcp --transport http
# Listening on http://127.0.0.1:3000/mcp

claude mcp add --transport http pushover http://127.0.0.1:3000/mcp
# With an auth token:
claude mcp add --transport http pushover https://pushover.example.com/mcp --header "Authorization: Bearer YOUR_AUTH_TOKEN"

Anyone who can reach the server can send notifications with your keys, so:

• It listens on 127.0.0.1 only, and rejects requests whose Host or Origin isn't local.
• To listen on other interfaces (for example --host 0.0.0.0), you must set an auth token. Clients then send Authorization: Bearer <token>.
• attachment_path is turned off, so clients can't read files from the server's disk.
• For remote access, put it behind HTTPS.

PUSHOVER_TOKEN=... PUSHOVER_USER=... PUSHOVER_MCP_AUTH_TOKEN=a-long-random-secret npx pushover-mcp --transport http --host 0.0.0.0

Use as a library

import { createServer, PushoverClient } from "pushover-mcp";

// An MCP server to mount on your own transport
const server = createServer({ token, user, defaults: { sound: "bike" } });

// Or call the Pushover API directly
await new PushoverClient({ token, user }).sendMessage({ message: "Deployed" });

Upgrading from v1

Existing v1 configs keep working: start, --token and --user are still accepted. What changed:

• The send tool is now send_notification. Agents pick up the new name automatically; update any prompts that name it.
• Node.js 22 or later is required.
• Library users: PushoverMCP is replaced by createServer().

See the changelog for details.

Development

pnpm install
pnpm dev        # run from source
pnpm check      # lint, typecheck, test
pnpm build
pnpm inspect    # open the server in MCP Inspector

Thanks

To everyone whose reports and pull requests shaped v2:

• @jtenniswood reported the Claude Desktop startup error (#3).
• @bcdonadio proposed the move to the newer MCP spec (#6).
• @craigles75 proposed HTML formatting (#9).
• @webbrain-one proposed the stderr logging fix (#10).
• @punkpeye flagged the Docker setup for the Glama directory (#4).
• @calclavia added the original Docker setup (#2).

License

MIT