# MCP Notification

Push notifications for AI developers, delivered via MCP. Get notifications from Claude Desktop, Claude Code, Cursor, and Windsurf on your mobile device.

## Quick Start

### Method 1: Automated Setup (Recommended)

The easiest way to get started:

```bash
npm install -g mcp-notification
mcp-notification setup
```

The setup wizard will automatically detect and configure your AI clients:
- Claude Desktop
- Claude Code CLI
- Cursor
- Windsurf

### Method 2: Manual Configuration

If you prefer manual setup, add to your client's config file:

**Claude Desktop** (`~/.claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}
```

**Claude Code CLI**:
```bash
claude mcp add --transport stdio --scope user notify -- npx -y mcp-notification
```

**Cursor** (`.cursor/mcp.json` or global config):
```json
{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "mcp-notification"]
    }
  }
}
```

### Method 3: npx On-Demand

Use without global installation (always uses latest version):

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

## Setup

1. Install the MCP Notify app on your iPhone (App Store)
2. In Claude Code, say "pair my phone"
3. Scan the QR code with the app
4. Done! Start receiving notifications.

## Usage

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

## Commands

| Command | Description |
|---------|-------------|
| pair my phone | Start QR code pairing |
| send notification | Send a push notification |
| show quota | Check usage limits |
| list devices | Show paired devices |

## MCP Tools

This server provides the following MCP tools:

| Tool | Description | Parameters |
|------|-------------|------------|
| `pair_device` | Start QR code pairing | `device_name?` |
| `check_pairing_status` | Check if QR was scanned | None |
| `get_setup_status` | Check if ready to use | None |
| `send_notification` | Send a push notification | `title`, `body?`, `priority?`, `url?`, `tags?` |
| `get_history` | View notification history | `limit?`, `tags?` |
| `get_quota` | Check usage limits | None |
| `list_devices` | List paired devices | None |
| `remove_device` | Remove a device | `device_id` |

## Configuration

### Environment Variables

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

### Credential Storage

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

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

## Troubleshooting

### Setup Wizard Not Working?

If the automated setup fails, try manual configuration or check:
- Permissions on config files
- Client is properly installed
- For Claude Code: `claude --version` should work

### Already Configured?

If you previously used `mcp-notify`, the new `mcp-notification` package replaces it. Both bin commands (`mcp-notification` and `mcp-notify`) work for backward compatibility.

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

# Start in development mode
npm run dev
```

## Publishing

```bash
# Build the project
npm run build

# Publish to npm (requires npm login)
npm publish
```

## Links

- Website: https://mcpnotify.dev
- iOS App: App Store
- Support: support@mcpnotify.dev

## License

MIT