Ntfy MCP サーバー
ntfyプッシュ通知サービスと連携するために設計されたMCP（モデルコンテキストプロトコル）サーバー。LLMやAIエージェントが、豊富なカスタマイズオプションを使用してデバイスに通知を送信できるようにします。
目次
概要
このサーバーは、モデルコンテキストプロトコル（MCP）を実装し、LLMと外部システム間の標準化された通信を可能にします。具体的には、ntfyプッシュ通知サービスへのインターフェースを提供します。
Ntfyは、シンプルなHTTPベースのpub-sub通知サービスで、シンプルなHTTPリクエストを介してスマートフォンやデスクトップに通知を送信できます。このMCPサーバーを使用すると、ClaudeのようなLLMエージェントは、直接HTTPアクセスすることなく、ntfy経由で通知を送信できます。
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐
│ LLM Agent │ ────▶│ Ntfy MCP │ ────▶│ Ntfy │ ────▶│ Your │
│ (Claude) │ │ Server │ │ Service │ │ Devices │
└───────────┘ └───────────┘ └───────────┘ └─────────┘
特徴
- MCP サーバー実装: LLM エージェントとのシームレスな統合のために
@modelcontextprotocol/sdkを使用して構築されました。 - **Ntfy 統合:**次のサポートを含む通知を送信するためのツール (
send_ntfy ) を提供します:- メッセージの優先順位（1～5段階）
- 絵文字タグ
- クリック可能なアクションとボタン
- 添付ファイル
- 配送遅延
- Markdownフォーマット
- **リソースの公開:**構成されたデフォルトの ntfy トピックを MCP リソースとして公開します。
- **TypeScript:**包括的な型定義を備えた最新の型セーフなコードベース。
- **構造化ログ:**詳細かつローテーション可能なログには
winstonとwinston-daily-rotate-file使用します。 - **構成管理:**環境ベースの構成を簡単にするために
dotenv使用します。 - **ユーティリティ スクリプト:**ビルド成果物をクリーンアップし、ディレクトリ構造のドキュメントを生成するためのスクリプトが含まれています。
- **エラー処理とセキュリティ:**堅牢なエラー処理、入力サニタイズ (
sanitize-html )、およびセキュリティ フィルター ( xss-filters ) を実装します。
クイックスタート
- 前提条件:
- Node.js (v16+)
- npmまたはyarn
- 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
オプション2: ソースから
- リポジトリをクローンします。
git clone https://github.com/cyanheads/ntfy-mcp-server.git
cd ntfy-mcp-server
- 依存関係をインストールします:
- プロジェクトをビルドします。
構成
環境変数
.env.exampleに基づいてプロジェクト ルートに.envファイルを作成します。
# 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 設定ファイル (通常、macOS では~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonにあります) に次の構成を追加します。
グローバルにインストールされている場合:
{
"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デスクトップアプリ
Claude Desktop 構成ファイル (通常、macOS では~/Library/Application Support/Claude/claude_desktop_config.jsonにあります) に次の構成を追加します。
グローバルにインストールされている場合:
{
"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 to/ntfy-mcp-server/dist/index.js をビルドしたサーバーファイルへの実際の絶対パスに置き換えてください。 必要に応じてenv変数を調整してください。
Ntfyセットアップ
- ntfy.shまたはアプリストアからデバイスにntfyアプリをインストールします。
- アプリでトピックを購読する
- 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 | 弦 | いいえ | メッセージの一意の ID。 |
expires | 弦 | いいえ | メッセージの有効期限 (例: 10m 、 1h 、 1d )。 |
markdown | ブール値 | いいえ | メッセージでマークダウン形式を有効にするには、 trueに設定します。 |
baseUrl | 弦 | いいえ | この要求のデフォルトの ntfy サーバー URL を上書きします。 |
使用例:
// 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_DEFAULT_TOPIC ) で設定されているデフォルトの ntfy トピックを返します。 - **使用法:**事前の構成を必要とせずにクライアントが主要なトピックを検出するのに役立ちます。
- 例: 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 ソース コードをdist/ディレクトリ内の JavaScript にコンパイルします。npm run clean : dist/ディレクトリを削除し、 logs/ディレクトリの内容を消去します。npm run rebuild : cleanを実行してからビルドbuild 。npm run tree : docs/tree.mdにディレクトリツリー表現を生成します。npm start : Node.js を使用してdist/ディレクトリからコンパイルされたサーバーを実行します。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ファイルをご覧ください。
謝辞