mcp-notify

<h1 align="center">MCP Notify</h1>

Push notifications for AI developers, delivered via MCP

Get real-time notifications from Claude Desktop, Claude Code, Cursor, and Windsurf on your mobile device.

<a href="#quick-start">Quick Start</a> • <a href="#installation">Installation</a> • <a href="#usage">Usage</a> • <a href="#mcp-tools">MCP Tools</a> • <a href="#how-it-works">How It Works</a>

---

Why MCP Notify?

Ever started a long-running AI task and walked away, only to come back wondering if it finished? MCP Notify solves this by sending push notifications directly to your phone.

Stay Informed — Get notified when builds complete, tests pass, or tasks finish
Works Everywhere — Claude Desktop, Claude Code CLI, Cursor, Windsurf
Simple Setup — One command to install, QR code to pair
Privacy First — Notifications are encrypted and never stored longer than needed

---

Quick Start

1. Install the MCP server:

npx -y mcp-notification setup

2. Download the iOS app:

3. Pair your device:

In your AI client, just say: > "Pair my phone"

Scan the QR code with the app. Done!

---

Installation

Automated Setup (Recommended)

Run the setup wizard — it automatically detects and configures your AI clients:

npx -y mcp-notification setup

The wizard supports:

✅ Claude Desktop
✅ Claude Code CLI
✅ Cursor
✅ Windsurf

Manual Configuration

<details> <summary>Claude Desktop</summary>

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}

</details>

<details> <summary>Claude Code CLI</summary>

claude mcp add --transport stdio --scope user notify -- npx -y mcp-notification

</details>

<details> <summary>Cursor</summary>

Add to .cursor/mcp.json or global config:

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}

</details>

<details> <summary>Windsurf</summary>

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}

</details>

After configuration, restart your AI client to load the MCP server.

---

Usage

Just talk naturally to your AI assistant:

"Notify me when you're done"
"Send a notification that the build completed"
"What's my notification quota?"
"List my paired devices"
"Remove my old phone"

Example Workflows

Long-running tasks: > "Run the full test suite and notify me when it's done"

Build monitoring: > "Build the project. If it succeeds, notify me with 'Build passed'. If it fails, send a high priority notification with the error."

Scheduled reminders: > "Send me a notification in 5 minutes to check the deployment"

---

MCP Tools

| Tool | Description | Parameters | |------|-------------|------------| | pair_device | Display QR code for pairing | device_name? | | check_pairing_status | Check if QR was scanned | — | | get_setup_status | Check if ready to send notifications | — | | send_notification | Send a push notification | title, body?, priority?, url?, tags? | | get_history | View notification history | limit?, tags? | | get_quota | Check monthly usage limits | — | | list_devices | List all paired devices | — | | remove_device | Unpair a device | device_id |

Notification Priority Levels

| Priority | Behavior | |----------|----------| | low | Silent delivery | | normal | Standard notification (default) | | high | Prominent alert | | critical | Bypasses Do Not Disturb |

---

How It Works

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   AI Client     │         │   MCP Server    │         │   iOS App       │
│  (Claude, etc)  │◀───────▶│ (mcp-notification)│◀───────▶│  (MCP Notify)   │
└─────────────────┘   MCP   └─────────────────┘   APNs  └─────────────────┘
                    Protocol        │
                                    │
                            ┌───────▼───────┐
                            │  Notify API   │
                            │ (mcpnotify.dev)│
                            └───────────────┘

Command Detection:

The package automatically detects how it's being invoked:

| Invocation | Result | |------------|--------| | mcp-notification setup | Setup wizard (always) | | mcp-notification in terminal | Setup wizard (TTY detected) | | Spawned by AI client | MCP stdio server (no TTY) | | mcp-notification server | MCP server (always) |

This is achieved by checking process.stdin.isTTY — when you run it in a terminal, stdin is connected to a TTY. When an AI client spawns it, stdin is a pipe for MCP JSON-RPC communication.

---

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MCP_NOTIFY_API_URL | Backend API URL | https://api.mcpnotify.dev/v1 |

Credential Storage

Credentials are stored locally in ~/.mcp-notify/:

~/.mcp-notify/
├── credentials.json    # API key and user info
└── pairing_state.json  # Temporary pairing data

---

Troubleshooting

Setup wizard not detecting my client?

Make sure the client is installed and working
Check that config files exist and are writable
Try manual configuration instead

Notifications not arriving?

Check pairing status: say "check pairing status" to your AI
Verify the iOS app has notification permissions enabled
Check your quota: say "what's my quota"

"Already configured" message?

The setup wizard detects existing configurations. To reconfigure:

Remove the existing entry from your client's config file
Run the setup wizard again

---

Development

# Clone the repo
git clone https://github.com/box7e7/mcp-notify
cd mcp-notify

# Install dependencies
npm install

# Build
npm run build

# Test setup wizard locally
npm link
mcp-notification setup

# Run tests
npm test

# Development mode (watch)
npm run dev

Project Structure

mcp-notify/
├── src/
│   ├── index.ts              # Entry point (TTY detection)
│   ├── cli/
│   │   ├── setup.ts          # Setup wizard
│   │   ├── config-manager.ts # Client config management
│   │   └── platform-detector.ts
│   ├── tools/
│   │   ├── pairing.tools.ts  # Device pairing
│   │   ├── notification.tools.ts
│   │   └── account.tools.ts
│   └── services/
│       ├── api-client.ts     # Backend communication
│       ├── credentials.ts    # Local credential storage
│       └── qr-generator.ts   # QR code generation
├── package.json
└── tsconfig.json

---

License

MIT © box7e7

---

Built with ❤️ for the AI developer community

Why MCP Notify?

Quick Start

Installation

Automated Setup (Recommended)

Manual Configuration

Usage

Example Workflows

MCP Tools

Notification Priority Levels

How It Works

Configuration

Environment Variables

Credential Storage

Troubleshooting

Setup wizard not detecting my client?

Notifications not arriving?

"Already configured" message?

Development

Project Structure

Links

License

Related MCP servers

MCP servers by category