mcp-notify

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

Related MCP server: MCPing

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

Add to ~/.claude/claude_desktop_config.json:

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

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

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

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

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

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

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

Notification Priority Levels

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:

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

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