# Bark MCP Server

A Model Context Protocol (MCP) server for sending iOS push notifications via [Bark](https://github.com/Finb/Bark).

[![npm version](https://badge.fury.io/js/@metrovoc/bark-mcp-server.svg)](https://www.npmjs.com/package/@metrovoc/bark-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

This MCP server provides tools for AI assistants to send push notifications to iOS devices through Bark. It supports all Bark API features including:

### Core Tools

1. **send_bark_notification** - Send a single push notification
2. **send_bark_batch_notifications** - Send multiple notifications in batch
3. **check_bark_server_health** - Check if a Bark server is healthy

### Supported Bark Features

- **Basic notifications** with title, subtitle, and body
- **URL redirection** - Open links when notifications are tapped
- **Notification grouping** - Organize notifications by group
- **Custom icons** - Use custom notification icons (iOS 15+)
- **Sound customization** - Use custom notification sounds
- **Call notifications** - Play sound repeatedly for 30 seconds
- **Notification levels**:
  - `active` (default)
  - `timeSensitive` - Displayed during focus mode
  - `passive` - Silent notification
  - `critical` - Overrides silent/do not disturb modes
- **Badge management** - Set app icon badge numbers
- **Encryption support** - Send encrypted notifications

## Installation

### Quick Start (Recommended)

```bash
npx @metrovoc/bark-mcp-server
```

### Global Installation

```bash
npm install -g @metrovoc/bark-mcp-server
bark-mcp-server
```

### Local Installation

```bash
npm install @metrovoc/bark-mcp-server
npx @metrovoc/bark-mcp-server
```

## Environment Variables

For easier usage, set these environment variables:

- `BARK_KEY`: Your Bark device key (required for automatic usage)
- `BARK_SERVER_URL`: Bark server URL (optional, defaults to https://api.day.app)

## Usage

### With Claude Code

**Recommended (with environment variables):**
```bash
claude mcp add bark -e BARK_KEY=your-device-key -- npx -y @metrovoc/bark-mcp-server
```

**Manual configuration:**
```json
{
  "bark": {
    "command": "npx",
    "args": ["-y", "@metrovoc/bark-mcp-server"],
    "env": {
      "BARK_KEY": "your-device-key",
      "BARK_SERVER_URL": "https://api.day.app"
    }
  }
}
```

For detailed Claude Code setup instructions, see [CLAUDE.md](./CLAUDE.md).

### With Claude Desktop

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bark": {
      "command": "npx",
      "args": ["-y", "@metrovoc/bark-mcp-server"],
      "env": {
        "BARK_KEY": "your-device-key",
        "BARK_SERVER_URL": "https://api.day.app"
      }
    }
  }
}
```

### Alternative Configuration Methods

**Global Installation:**
```bash
claude mcp add bark -e BARK_KEY=your-device-key -- bark-mcp-server
```

**Direct Node.js:**
```bash
claude mcp add bark -e BARK_KEY=your-device-key -- node /path/to/@metrovoc/bark-mcp-server/build/index.js
```

### With MCP Inspector

For testing and debugging:

```bash
npx @modelcontextprotocol/inspector npx @metrovoc/bark-mcp-server
```

With environment variables:
```bash
BARK_KEY=your-device-key npx @modelcontextprotocol/inspector npx @metrovoc/bark-mcp-server
```

## AI Collaboration Features

This MCP server is specifically designed to enable efficient **human-AI collaboration**. AI assistants like Claude Code can use these tools to:

- 🚨 **Alert you when errors require intervention**
- ✅ **Notify when tasks are completed and ready for review**  
- 🤔 **Request decisions when user input is needed**
- 🧪 **Summon you for testing and verification**
- 📊 **Provide progress updates on long-running operations**

The intelligent tool descriptions guide AI to choose appropriate notification priorities and timing, enabling you to focus on other work while AI handles routine tasks.

## Tool Reference

### send_bark_notification

Send a single push notification to an iOS device. **AI assistants should use this to notify users when tasks complete, errors occur, or input is needed.**

**Parameters:**
- `body` (required) - Notification content/message
- `server_url` (optional) - Bark server URL (defaults to BARK_SERVER_URL env var or https://api.day.app)
- `device_key` (optional) - Device key (defaults to BARK_KEY env var)
- `title` (optional) - Notification title
- `subtitle` (optional) - Notification subtitle
- `url` (optional) - URL to open when notification is tapped
- `group` (optional) - Group name for organizing notifications
- `icon` (optional) - Custom icon URL (iOS 15+)
- `sound` (optional) - Custom notification sound name
- `call` (optional) - Play sound repeatedly for 30 seconds (use for critical issues)
- `level` (optional) - **Priority level**:
  - `critical`: Urgent issues requiring immediate attention (errors, failures)
  - `timeSensitive`: Important updates during focus mode (task completion, testing needed)
  - `active`: General notifications (progress updates)
  - `passive`: Low-priority background info
- `badge` (optional) - Badge number on app icon
- `ciphertext` (optional) - Encrypted message content

**AI Usage Examples:**
```json
// Critical error requiring immediate attention
{
  "body": "❌ Build failed with 5 errors. Your immediate attention required.",
  "title": "Critical: Build Failure", 
  "level": "critical",
  "call": true
}

// Task completion notification
{
  "body": "✅ User authentication system completed. Ready for testing.",
  "title": "Task Complete",
  "level": "timeSensitive"
}

// Progress update
{
  "body": "📊 Database migration completed successfully (3/5 steps done).",
  "title": "Progress Update",
  "level": "active"
}
```

### send_bark_batch_notifications

Send multiple notifications in a single batch operation. **Use for notifying multiple team members or sending different priority updates.**

**Parameters:**
- `notifications` (required) - Array of notification objects (same format as single notification)
- `server_url` (optional) - Bark server URL (defaults to BARK_SERVER_URL env var or https://api.day.app)

### check_bark_server_health

Check if a Bark server is running and healthy. **AI should call this proactively to ensure reliable user communication.**

**Parameters:**
- `server_url` (optional) - Bark server URL to check (defaults to BARK_SERVER_URL env var or https://api.day.app)

## Getting Your Device Key

1. Install [Bark app](https://apps.apple.com/us/app/bark-custom-notifications/id1403753865) on your iOS device
2. Open the app and copy your device key from the main screen
3. Use this key in the `device_key` parameter

## Bark Server Setup

You can use:
- The official Bark service: `https://api.day.app`
- Self-hosted Bark server (see [bark-server](https://github.com/Finb/bark-server))

## Development

```bash
# Watch mode for development
npm run dev

# Build
npm run build

# Start the server
npm start
```

## License

MIT License