NTFY MCP-сервер

Ntfy MCP-сервер

Сервер MCP (Model Context Protocol), разработанный для взаимодействия с сервисом push-уведомлений ntfy . Он позволяет LLM и агентам AI отправлять уведомления на ваши устройства с обширными возможностями настройки.

Обзор

Этот сервер реализует протокол Model Context Protocol (MCP), обеспечивая стандартизированную связь между LLM и внешними системами. В частности, он предоставляет интерфейс для службы push-уведомлений ntfy.

Ntfy — это простая служба уведомлений pub-sub на основе HTTP, которая позволяет отправлять уведомления на ваш телефон или рабочий стол с помощью простых HTTP-запросов. С этим MCP-сервером агенты LLM, такие как Клод, могут отправлять вам уведомления через ntfy без необходимости прямого HTTP-доступа.

┌───────────┐      ┌───────────┐      ┌───────────┐      ┌─────────┐
│ LLM Agent │ ────▶│ Ntfy MCP  │ ────▶│ Ntfy      │ ────▶│ Your    │
│ (Claude)  │      │ Server    │      │ Service   │      │ Devices │
└───────────┘      └───────────┘      └───────────┘      └─────────┘

Функции

Реализация сервера MCP: создана с использованием @modelcontextprotocol/sdk для бесшовной интеграции с агентами LLM.
Интеграция с Ntfy: предоставляет инструмент ( send_ntfy ) для отправки уведомлений с поддержкой:
- Приоритезация сообщений (1-5 уровней)
- Теги эмодзи
- Действия и кнопки, активируемые нажатием
- Прикрепленные файлы
- Задержка доставки
- Форматирование Markdown
Раскрытие ресурса: раскрывает настроенную по умолчанию тему ntfy как ресурс MCP.
TypeScript: современная, типобезопасная кодовая база с подробными определениями типов.
Структурированное ведение журналов: использует winston и winston-daily-rotate-file для подробных и ротируемых журналов.
Управление конфигурацией: использует dotenv для простой настройки на основе среды.
Скрипты утилит: включают скрипты для очистки артефактов сборки и создания документации по структуре каталогов.
Обработка ошибок и безопасность: реализует надежную обработку ошибок, очистку входных данных ( sanitize-html ) и фильтры безопасности ( xss-filters ).

Быстрый старт

Предварительные условия:
- Node.js (v16+)
- нпм или пряжа
- Клиент, совместимый с MCP (Claude Desktop, Cline и т. д.)
Установить и запустить:
# Option 1: Install via npm npm install -g ntfy-mcp-server # Option 2: Clone repository and build git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server npm install npm run build # Create .env file (optional but recommended) cp .env.example .env # Edit .env to set NTFY_DEFAULT_TOPIC # Start the server npm start
Добавить в настройки клиента MCP: добавьте сервер в файл настроек клиента MCP (см. Конфигурация ).
Использование инструмента: После подключения вы можете использовать инструмент send_ntfy для отправки уведомлений.

Установка

Вариант 1: Пакет NPM (рекомендуется)

Установите пакет глобально:
npm install -g ntfy-mcp-server
Это установит сервер глобально и сделает его доступным как инструмент командной строки.
Или установите локально в своем проекте:
npm install ntfy-mcp-server
При локальной установке вы можете запустить его через npx или из node.

Вариант 2: Из источника

Клонируйте репозиторий:
git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server
Установите зависимости:
npm install
Создайте проект:
npm run build

Конфигурация

Переменные среды

Создайте файл .env в корне проекта на основе .env.example :

# Ntfy Configuration
NTFY_BASE_URL=https://ntfy.sh  # Optional: Base URL of your ntfy instance
NTFY_DEFAULT_TOPIC=your_default_topic # Optional: Default topic if none specified in requests

# Application Configuration
LOG_LEVEL=info # Optional: Logging level (debug, info, warn, error)
NODE_ENV=development # Optional: Environment (development, production)

Настройки клиента MCP

Для расширения Cline VSCode

Добавьте следующую конфигурацию в файл настроек Cline MCP (обычно он находится по адресу ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json в macOS):

При глобальной установке:

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Если установлено из источника:

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Для приложения Claude Desktop

Добавьте следующую конфигурацию в файл конфигурации Claude Desktop (обычно он находится в ~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

При глобальной установке:

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Если установлено из источника:

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Для установки исходного кода замените /path/to/ntfy-mcp-server/dist/index.js на фактический абсолютный путь к файлу построенного сервера. Отрегулируйте переменные env по мере необходимости для вашей настройки.

Настройка NTFy

Установите приложение ntfy на свои устройства с ntfy.sh или из магазинов приложений.
Подпишитесь на свою тему в приложении
Используйте ту же тему в конфигурации вашего сервера MCP

Структура проекта

.
├── .env.example            # Example environment variables
├── .gitignore              # Git ignore patterns
├── LICENSE                 # Project license (Apache-2.0)
├── package.json            # Project metadata and dependencies
├── tsconfig.json           # TypeScript compiler configuration
├── docs/
│   └── tree.md             # Auto-generated directory structure
├── logs/                   # Runtime logs (created automatically)
├── scripts/                # Utility scripts
│   ├── clean.ts            # Cleans build artifacts and logs
│   └── tree.ts             # Generates the docs/tree.md file
└── src/                    # Source code
    ├── index.ts            # Main server entry point
    ├── config/             # Configuration loading
    ├── mcp-server/         # MCP server logic, tools, and resources
    │   ├── resources/      # MCP resource implementations
    │   ├── tools/          # MCP tool implementations
    │   └── utils/          # MCP-specific utilities
    ├── services/           # External service integrations (ntfy)
    ├── types-global/       # Global type definitions
    └── utils/              # General utility functions

Инструменты

`send_ntfy`

Отправляет уведомление через службу ntfy.

Основные аргументы:

Параметр	Тип	Необходимый	Описание
`topic`	нить	Да	Тема ntfy для публикации.
`message`	нить	Да	Основное содержание уведомления (макс. 4096 байт).
`title`	нить	Нет	Заголовок уведомления (макс. 250 байт).
`tags`	нить[]	Нет	Эмодзи или ключевые слова для категоризации (например, `["warning", "robot"]` ). Макс. 5.
`priority`	целое число	Нет	Приоритет сообщения: 1=мин., 2=низкий, 3=по умолчанию, 4=высокий, 5=макс.
`click`	нить	Нет	URL-адрес, который будет открываться при нажатии на уведомление.
`actions`	множество	Нет	Кнопки действий (просмотр, http, трансляция). Макс. 3.
`attachment`	объект	Нет	URL и имя вложения.
`email`	нить	Нет	Адрес электронной почты для пересылки уведомления.
`delay`	нить	Нет	Задержка доставки (например, `30m` , `1h` , `tomorrow` ).
`cache`	нить	Нет	Длительность кэширования (например, `10m` , `1h` , `1d` ).
`firebase`	нить	Нет	Тема Firebase Cloud Messaging (FCM) для пересылки.
`id`	нить	Нет	Уникальный идентификатор сообщения.
`expires`	нить	Нет	Срок действия сообщения (например, `10m` , `1h` , `1d` ).
`markdown`	булев	Нет	Установите значение `true` , чтобы включить форматирование markdown в сообщении.
`baseUrl`	нить	Нет	Переопределить URL-адрес сервера ntfy по умолчанию для этого запроса.

Пример использования:

// Basic notification
{
  "topic": "alerts",
  "message": "The task has completed successfully."
}

// Advanced notification
{
  "topic": "alerts",
  "title": "System Alert",
  "message": "CPU usage has exceeded 90% for 5 minutes.",
  "tags": ["warning", "computer"],
  "priority": 4,
  "click": "https://server-dashboard.example.com",
  "actions": [
    {
      "id": "view",
      "label": "View Details",
      "action": "view",
      "url": "https://server-dashboard.example.com/cpu"
    },
    {
      "id": "restart",
      "label": "Restart Service",
      "action": "http",
      "url": "https://api.example.com/restart-service",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  ],
  "markdown": true
}

Пример ответа:

{
  "success": true,
  "id": "5ZFY362156Sa",
  "topic": "ATLAS",
  "time": 1743064235,
  "expires": 1743496235,
  "message": "This is a test message from the README verification process",
  "title": "README Testing"
}

Ресурсы

Прямые Ресурсы

`ntfy://default`

Описание: Возвращает тему ntfy по умолчанию, настроенную в переменных среды сервера ( NTFY_DEFAULT_TOPIC ).
Использование: полезно для клиентов, желающих узнать основную тему без необходимости предварительной настройки.
Пример: агент LLM может получить доступ к этому ресурсу, чтобы автоматически использовать тему по умолчанию при отправке уведомлений.
Пример ответа:
{ "defaultTopic": "ATLAS", "timestamp": "2025-03-27T08:30:25.619Z", "requestUri": "ntfy://default", "requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484" }

Шаблоны ресурсов

`ntfy://{topic}`

Описание: Возвращает информацию о конкретной теме ntfy.
Параметры: topic - Название темы ntfy.
Использование: Для запроса информации по темам, отличным от тем по умолчанию.
Пример ответа:
{ "topic": "ATLAS", "timestamp": "2025-03-27T08:30:30.038Z", "requestUri": "ntfy://ATLAS", "requestId": "31baf1df-278f-4fdb-860d-019f156a72b0" }

Варианты использования

Уведомления о длительных задачах — получайте уведомления о завершении таких задач, как резервное копирование базы данных, генерация кода или обработка данных.
Запланированные напоминания — установите отложенные уведомления для будущих событий или напоминаний.
Системы оповещений — настройте критические оповещения для систем мониторинга или важных событий.
Мобильные уведомления от LLM — разрешите LLM отправлять уведомления прямо на ваш телефон.
Обновления многоэтапного процесса — получайте обновления по мере завершения различных этапов сложного процесса.

Примеры использования

Базовое уведомление

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "updates",
  "title": "Task Completed",
  "message": "Your requested data analysis has finished",
  "tags": ["check"]
}
</arguments>
</use_mcp_tool>

Расширенное уведомление с действиями

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "alerts",
  "title": "Critical Error Detected",
  "message": "The application has encountered a critical error.\n\n**Error Code**: E123\n\n**Details**: Database connection failed",
  "tags": ["warning", "skull"],
  "priority": 5,
  "actions": [
    {
      "id": "view",
      "label": "View Logs",
      "action": "view",
      "url": "https://logs.example.com"
    },
    {
      "id": "restart",
      "label": "Restart Service",
      "action": "http",
      "url": "https://api.example.com/restart",
      "method": "POST"
    }
  ],
  "markdown": true
}
</arguments>
</use_mcp_tool>

Доступные сценарии

npm run build : компилирует исходный код TypeScript в JavaScript в каталоге dist/ .
npm run clean : удаляет каталог dist/ и очищает содержимое каталога logs/ .
npm run rebuild : выполняет clean , а затем build .
npm run tree : создает представление дерева каталогов в docs/tree.md .
npm start : запускает скомпилированный сервер из каталога dist/ с помощью Node.js.
npm run watch : отслеживает объединенный файл журнала ( logs/combined.log ) для мониторинга в реальном времени.

Внося вклад

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запросы на включение изменений или открытые вопросы для улучшения проекта.

Создайте форк репозитория.
Создайте ветку функций ( git checkout -b feature/your-feature ).
Зафиксируйте изменения ( git commit -m 'Add some feature' ).
Отправьте изменения в ветку ( git push origin feature/your-feature ).
Создайте новый запрос на извлечение.

Для сообщений об ошибках и запросов на новые функции, пожалуйста, создайте запрос в репозитории.

Лучшие практики разработки

Следуйте лучшим практикам TypeScript и поддерживайте строгую типизацию
Написание тестов для новых функций
Поддерживайте зависимости в актуальном состоянии
Следуйте существующему стилю и шаблонам кода.

Лицензия

Этот проект лицензирован по лицензии Apache-2.0. Подробности смотрите в файле LICENSE .

Благодарности

ntfy.sh для предоставления услуги уведомления
Протокол контекста модели для обеспечения соединений LLM с инструментом
Все участники и пользователи этого проекта

Integrations