README - bark-mcp-server by metrovoc

Bark MCP Server

A Model Context Protocol (MCP) server for sending iOS push notifications via Bark.

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

send_bark_notification - Send a single push notification
send_bark_batch_notifications - Send multiple notifications in batch
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)

npx @metrovoc/bark-mcp-server

Global Installation

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

Local Installation

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

claude mcp add bark -e BARK_KEY=your-device-key -- npx -y @metrovoc/bark-mcp-server

Manual configuration:

{
  "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 .

With Claude Desktop

Add the server to your claude_desktop_config.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:

claude mcp add bark -e BARK_KEY=your-device-key -- bark-mcp-server

Direct Node.js:

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:

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

With environment variables:

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:

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

Install Bark app on your iOS device
Open the app and copy your device key from the main screen
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)

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Start the server
npm start

License

MIT License