mcp-notify

<p align="center"> <img src="https://mcpnotify.dev/logo.png" alt="MCP Notify Logo" width="120" height="120"> </p>

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

<p align="center"> <strong>Push notifications for AI developers, delivered via MCP</strong> </p>

<p align="center"> Get real-time notifications from Claude Desktop, Claude Code, Cursor, and Windsurf on your mobile device. </p>

<p align="center"> <a href="https://www.npmjs.com/package/mcp-notification"><img src="https://img.shields.io/npm/v/mcp-notification.svg" alt="npm version"></a> <a href="https://www.npmjs.com/package/mcp-notification"><img src="https://img.shields.io/npm/dm/mcp-notification.svg" alt="npm downloads"></a> <a href="https://github.com/box7e7/mcp-notify/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/mcp-notification.svg" alt="license"></a> <a href="https://github.com/box7e7/mcp-notify"><img src="https://img.shields.io/github/stars/box7e7/mcp-notify.svg?style=social" alt="GitHub stars"></a> </p>

<p align="center"> <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> </p>

---

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:

<a href="https://apps.apple.com/app/mcp-notify/id123456789"> <img src="https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg" alt="Download on App Store" height="50"> </a>

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><strong>Claude Desktop</strong></summary>

Add to ~/.claude/claude_desktop_config.json:

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

</details>

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

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

</details>

<details> <summary><strong>Cursor</strong></summary>

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

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

</details>

<details> <summary><strong>Windsurf</strong></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?

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

Notifications not arriving?

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

"Already configured" message?

The setup wizard detects existing configurations. To reconfigure:

1. Remove the existing entry from your client's config file
2. 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

---

Links

• Website: https://mcpnotify.dev
• iOS App: App Store
• npm: https://www.npmjs.com/package/mcp-notification
• Support: support@mcpnotify.dev

---

License

MIT © box7e7

---

<p align="center"> _{Built with ❤️ for the AI developer community} </p>