# Pushpad MCP

[![CI](https://github.com/pushpad/pushpad-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pushpad/pushpad-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/pushpad-mcp?color=blue)](https://www.npmjs.com/package/pushpad-mcp)

[Pushpad](https://pushpad.xyz) MCP server for sending web push notifications and managing resources on Pushpad (CRUD actions on notifications, subscriptions, projects and senders) using the [Pushpad API](https://pushpad.xyz/docs/rest_api).

This project is a thin layer built on top of the Pushpad API, using the official [Pushpad OpenAPI spec](https://github.com/pushpad/pushpad-openapi) and [FastMCP for TypeScript](https://github.com/PrefectHQ/fastmcp-ts).

## Security

Use of MCP technology to interact with your Pushpad account can come with risks.

This MCP server gives full access to the Pushpad API, which includes irreversible and destructive actions (like update, delete, etc.). The API can also return sensitive data like push subscription keys (Subscriptions API) and VAPID keys (Senders API).

We recommend using an appropriate *permission mode* in your agent and using a Pushpad token with *restricted access*.

You can change the permission mode to *Manual* or set *allow* / *deny* permissions for the different tools provided by this MCP server in your agent settings.

We recommend *excluding the VAPID keys* stored in Senders from your AI context: you can either use a Pushpad token with restricted access or deny the tools that give access to Senders API.

Remember to *keep the access token private* and never store it in the Git repository.

## Installation

### Step 1: Set Up Your API Token as an Environment Variable

First, you need to **create a new Pushpad token**: open the Pushpad dashboard, click your account name, then click *Access tokens* and create a new token.

Then you need to **store the Pushpad token as an environment variable**. You can set it globally on your machine (`~/.bashrc`, `~/.zshrc`, or another shell profile), use a password manager (like 1Password CLI), set it in a project specific `.env` file, or add it directly to the MCP client configuration file (like `.mcp.json`). Remember to add `.env`, `.mcp.json` or other files that may include the secret to `.gitignore`.

### Step 2: Add the MCP Server to Your AI Agent

The local MCP server is launched directly by your MCP client using the settings defined in your MCP JSON configuration file. The exact location of this file and how it is applied depends on your MCP client.

To enable the MCP services, add an entry to the `mcpServers` block:

```json
{
  "mcpServers": {
    "pushpad": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pushpad-mcp"],
      "env": {
        "PUSHPAD_TOKEN": "${PUSHPAD_TOKEN}"
      }
    }
  }
}
```

The above example configures the Pushpad MCP server with `${PUSHPAD_TOKEN}`. Replace it with your Pushpad token or use the client-specific method of variable substitution (if available) to keep your token out of the configuration file.

### Step 3: Use the Pushpad MCP

Finally you can interact with Pushpad using MCP and your AI agent.

For example:

> Use Pushpad to send everyone a notification about XYZ.

> Send a notification to user 123 using Pushpad.

> How many clicks received the notification 98765?

> What is the default TTL for notifications in project 456?

The MCP server supports the full Pushpad API, including the Notifications API, Subscriptions API, Projects API and Senders API.

## Development

If you want to contribute to this project, feel free to open an issue or submit a pull request.

If you want to make changes to this package, for local development, you can clone this repo and use VS Code with a *dev container* for easier setup.

Then you can use the following commands:

- `npm run build` to compile the TypeScript project
- `npm run start` to start the MCP server
- `npm run inspect` to start the MCP server and inspect it with `@modelcontextprotocol/inspector`

You can set the `PUSHPAD_TOKEN` in an `.env` file and it is read automatically.

This repo also includes Claude Code in the dev container and an `.mcp.json` that you can use to try the local version of this MCP server. This is only useful if you plan to make changes to this package and you want to try the modifed version before submitting a pull request.

## License

This MCP server is released under an open source license (MIT).