Ntfy MCP-сервер

👁 Машинопись
👁 Модель контекстного протокола
👁 Версия
👁 Лицензия
👁 Статус
👁 GitHub

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

Оглавление

• Обзор

• Функции

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

• Установка

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

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

• Инструменты

• Ресурсы

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

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

• Внося вклад

• Лицензия

Related MCP server: ntfy-me-mcp

Обзор

Этот сервер реализует протокол 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 ).

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

1. Предварительные условия:

   • Node.js (v16+)

   • нпм или пряжа

   • Клиент, совместимый с MCP (Claude Desktop, Cline и т. д.)

2. Установить и запустить:

   # 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

3. Добавить в настройки клиента MCP: добавьте сервер в файл настроек клиента MCP (см. Конфигурация ).

4. Использование инструмента: После подключения вы можете использовать инструмент send_ntfy для отправки уведомлений.

Установка

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

1. Установите пакет глобально:

   npm install -g ntfy-mcp-server

   Это установит сервер глобально и сделает его доступным как инструмент командной строки.

2. Или установите локально в своем проекте:

   npm install ntfy-mcp-server

   При локальной установке вы можете запустить его через npx или из node.

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

1. Клонируйте репозиторий:

   git clone https://github.com/cyanheads/ntfy-mcp-server.git
   cd ntfy-mcp-server

2. Установите зависимости:

   npm install

3. Создайте проект:

   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

1. Установите приложение ntfy на свои устройства с ntfy.sh или из магазинов приложений.

2. Подпишитесь на свою тему в приложении

3. Используйте ту же тему в конфигурации вашего сервера 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.

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

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

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

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

1. Уведомления о длительных задачах — получайте уведомления о завершении таких задач, как резервное копирование базы данных, генерация кода или обработка данных.

2. Запланированные напоминания — установите отложенные уведомления для будущих событий или напоминаний.

3. Системы оповещений — настройте критические оповещения для систем мониторинга или важных событий.

4. Мобильные уведомления от LLM — разрешите LLM отправлять уведомления прямо на ваш телефон.

5. Обновления многоэтапного процесса — получайте обновления по мере завершения различных этапов сложного процесса.

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

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

<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 ) для мониторинга в реальном времени.

Внося вклад

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

1. Создайте форк репозитория.

2. Создайте ветку функций ( git checkout -b feature/your-feature ).

3. Зафиксируйте изменения ( git commit -m 'Add some feature' ).

4. Отправьте изменения в ветку ( git push origin feature/your-feature ).

5. Создайте новый запрос на извлечение.

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

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

• Следуйте лучшим практикам TypeScript и поддерживайте строгую типизацию

• Написание тестов для новых функций

• Поддерживайте зависимости в актуальном состоянии

• Следуйте существующему стилю и шаблонам кода.

Лицензия

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

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

• ntfy.sh для предоставления услуги уведомления

• Протокол контекста модели для обеспечения соединений LLM с инструментом

• Все участники и пользователи этого проекта

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers