<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:**

```bash
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:

```bash
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`:

```json
{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}
```
</details>

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

```bash
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:

```json
{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}
```
</details>

<details>
<summary><strong>Windsurf</strong></summary>

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

```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

```bash
# 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](https://apps.apple.com/app/mcp-notify/id123456789)
- **npm:** https://www.npmjs.com/package/mcp-notification
- **Support:** support@mcpnotify.dev

---

## License

MIT © [box7e7](https://github.com/box7e7)

---

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