ntfy-me-mcp

ntfy-me-mcp

ntfy サービス（パブリックまたはセルフホスト、トークン対応）を介して通知を送受信する、シンプルな Model Context Protocol（MCP）サーバーです 📲

概要

ntfy-me-mcp を使うと、AI アシスタントから ntfy.sh サービス（パブリック、またはトークン対応のセルフホスト）を通じて、デバイスにリアルタイム通知を送信できます。AI がタスクを完了したとき、エラーが発生したとき、または重要な節目に到達したときに、常に監視し続けなくても通知を受け取れます。

このサーバーには、表示アクションを作成するための URL の自動検出や、スマートな Markdown 形式の検出などの便利な機能が備わっています。追加設定なしで、AI アシスタントがリッチでインタラクティブな通知を作成しやすくなります。

プレビュー	利用可能な場所
	名称 リンク／バッジ ntfy.sh ntfy.sh の注目プロジェクト Glama.ai LightNow MseeP.ai Archestra.ai

近日公開予定...

• 📨 メール：メールに通知を送信します（ntfy メールサーバーの設定が必要です）
• 🖼️ 画像 URL：画像 URL をインテリジェントに検出し、メッセージや通知に自動で含めます
• 🏁 その他！

目次

クイックスタート - MCP サーバーの設定

クライアントに合った設定形式を選択してください。以下の例では、必須変数として NTFY_TOPIC を使用し、任意の認証設定は必要になるまでコメントアウトしています。

Ontheia でのテスト済み： セルフホスト可能なオープンソースの AI エージェントプラットフォームである Ontheia は、ntfy-me-mcp が動作することを報告しており、対応 MCP サーバーの一覧に掲載しています。

要件： npx、グローバル、ローカルの各オプションでは Node.js 24 以降が必要です。CI と Docker イメージでは Node 24 を使用します。Node 22 以前はサポートされていません（npm は EBADENGINE の警告を表示します）。Docker オプションに必要なのは Docker のみです。

設定例

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["-y", "ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://ntfy.sh",
      // "NTFY_TOKEN": "add-your-ntfy-token"
    }
  }
}

{
  "ntfy-me-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/ntfy-me-mcp/build/index.js"],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://ntfy.sh",
      // "NTFY_TOKEN": "add-your-ntfy-token"
    }
  }
}

{
  "ntfy-me-mcp": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "NTFY_TOPIC",
      "-e",
      "NTFY_URL",
      "-e",
      "NTFY_TOKEN",
      "gitmotion/ntfy-me-mcp:latest"
    ],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://ntfy.sh",
      // "NTFY_TOKEN": "add-your-ntfy-token"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ntfy-me-mcp": {
      "type": "local",
      "command": ["npx", "-y", "ntfy-me-mcp"],
      "environment": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://ntfy.sh",
        // "NTFY_TOKEN": "add-your-ntfy-token"
      }
    }
  }
}

{
  "mcpServers": {
    "ntfy-me-mcp": {
      "command": "npx",
      "args": ["-y", "ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://ntfy.sh",
        "NTFY_TOKEN": "${NTFY_TOKEN:-}"
      }
    }
  }
}

{
  "mcpServers": {
    "ntfy-me-mcp": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://ntfy.sh",
        "NTFY_TOKEN": "your-access-token"
      },
      "tools": ["*"]
    }
  }
}

[mcp_servers.ntfy-me-mcp]
command = "npx"
args = ["-y", "ntfy-me-mcp"]

[mcp_servers.ntfy-me-mcp.env]
NTFY_TOPIC = "your-ntfy-topic"
NTFY_URL = "https://ntfy.sh"
# NTFY_TOKEN = "your-access-token"

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["-y", "ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://your-ntfy-server.com",
      "NTFY_TOKEN": "your-access-token"
    }
  }
}

インストール

サーバーを直接インストールして実行する必要がある場合（上記のMCP設定の代替手段）：

# リポジトリのクローン、依存関係のインストール、.envの設定、ビルド、実行

git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp
npm install
cp .env.example .env
npm run build
npm start

通知受信側のセットアップ

設定

環境変数

例をコピーして.envファイルを作成します：cp .env.example .env。参考として.env.exampleを確認してください。

認証

// Add this to your VS Code `mcp.json` file, either the user-level file or your workspace `.vscode/mcp.json`
// Set `NTFY_TOKEN` exactly to `"${input:ntfy_token}"` when you want VS Code to treat it as a secure prompt-backed value.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ntfy_token",
      "description": "Ntfy Token",
      "password": true
    }
  ],
  "servers": {
    "ntfy-me-mcp": {
      "command": "npx",
      "args": ["-y", "ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://your-ntfy-server.com",
        "NTFY_TOKEN": "${input:ntfy_token}"
      }
    }
  }
}

ツールと使い方

ntfy_me：通知の送信

自然言語を使用する

• AI アシスタントを使用する際は、自然な表現で通知をリクエストできます。

"ntfyme with a summary of the task when complete"
"Send me a notification when the build is complete"
"Notify me when the task is done"
"Alert me after generating the code"
"Message me when the process finishes"
"Send an alert with high priority"

使用例

{
  "title": "コード生成完了",
  "message": "React コンポーネントが適切な
TypeScript の型付けとともに正常に
作成されました。",
  "priority": "high",
  "tags": ["white_check_mark", "code", "react"]
}

{
  "success": true,
  "endpoint": "https://ntfy.sh/ntfymetest"
}

メッセージのパラメーター

{
  title: "Task Complete",
  message: "Regular plain text message",
  markdown: false  // Force disable
}

{
  title: "Build Complete",
  message: "View at https://github.com/org/repo/pull/123"
}

{
  title: "Pull Request Review",
  message: "Ready for final checks",
  actions: [
    {
      action: "view",
      label: "View PR",
      url: "https://github.com/org/repo/pull/123"
    },
    {
      action: "view",
      label: "View Changes",
      url: "https://github.com/org/repo/pull/123/files",
      clear: true
    }
  ]
}

自然言語を使う

AI アシスタントは、メッセージの取得をさまざまな表現でリクエストできます。

"Show me my recent notifications"
"Get messages from the last hour"
"Find notifications with title 'Build Complete'"
"Search for messages with the test_tube tag"
"Show notifications from the updates topic from the last 24hr"  # needs updates in NTFY_TOPICS_ALLOWLIST (or NTFY_ALLOW_TOPIC_OVERRIDE=true)
"Check my latest alerts"

使用例

{
  "since": "6h"
}

{
  "success": true,
  "messageCount": 1,
  "topics": {
    "ntfymetest": [
      {
        "id": "On4Jeo1ENDCB",
        "time": 1775859291,
        "event": "message",
        "topic": "ntfymetest",
        "message": "Test",
        "title": "Test",
        "priority": 3,
        "expires": 1775902491
      }
    ]
  }
}

取得パラメーター

どちらのツールも、モデル向けの読みやすいcontentと、機械可読なstructuredContentオブジェクトを返します。ntfy_me_fetchのcontentには、取得したメッセージもJSONとして含まれます。このテキストはトピックに投稿した人が作成したものなので、信頼できないデータとして扱ってください（セキュリティを参照）。

無効な引数（titleがない、topicの形式が正しくない、未知のpriorityが指定されているなど）は、ツールの実行前にMCP SDKのスキーマ検証によって拒否されます。isError: trueと、フィールド名および期待される形式を示すテキストのみのメッセージMCP error -32602: Input validation error: …が返され、structuredContentは返されません。

ツール内での失敗では、isError: trueが設定され、{ "success": false, "error": "<message>" }が返されます。エラーメッセージには、無効なurlまたはtopic、認証の失敗（HTTP 401/403）、2xx以外のステータスコード（... Status code: 500）、ネットワークの失敗が具体的に示されます。接続できなかった場合はNodeのエラーコードを使って... could not connect to the ntfy server (ECONNREFUSED)、接続後に切断された場合は... the request to the ntfy server failed (ECONNRESET)と示されます（通知が配信されている可能性があります）。それ以外のエラーは一般的なメッセージ（Failed to send ntfy notification／Failed to fetch ntfy messages）で報告されるため、生の入力やサーバーのテキストがモデルに返されることはありません。エラーの詳細はサーバーの標準エラーログに書き込まれます。

セキュリティ

ntfy-me-mcp では、すべてのツール引数を信頼できないものとして扱います。プロンプトインジェクションされたコンテンツを読み込んだ可能性のあるモデルから渡されるためです。

• URL： url 引数と NTFY_URL のどちらからも、http:// と https:// のサーバー URL のみ受け付けます。認証情報が埋め込まれた URL（https://user:pass@…）は拒否されます。NTFY_TOKEN または accessToken を使用してください。
• 起動時のチェック： NTFY_TOPIC が未設定または無効の場合、あるいは NTFY_URL が無効（http(s) ではない、または user:pass@ を含む）の場合、サーバーは起動時に停止します。エラーには変数名が含まれ、stderr に書き込まれます。MCP クライアントのサーバーログで確認できます。サーバーは NTFY_URL をログに記録する前にこれらをチェックするため、埋め込み認証情報がログに記録されることはありません。
• トークンとログ： アクセストークンには、スペースを含まない印字可能な ASCII 文字のみ使用できます。エラーは stderr に書き込まれ、ベアラー値と URL 認証情報は伏せられます。
• トピック： 使用できるのは英字、数字、_、- のみで、最大 128 文字です。
• エラーメッセージ： 既知の安全なメッセージだけがモデルに渡されます。それ以外はすべて汎用メッセージに置き換えられるため、攻撃者が制御するテキストがそのまま返されることはありません（#13を参照）。
• 取得したメッセージは信頼できない入力です。 ntfy_me_fetch はメッセージの内容をモデルに渡します。また、公開トピックの名前を知っている人なら誰でも、そのトピックにメッセージを投稿できます。ntfy.sh では、推測しにくいトピック名を使用するか、アクセストークンで保護されたトピックを使用してください。
• 送信先の制御： デフォルトでは、すべての通知と取得先は NTFY_URL 上の NTFY_TOPIC です。エージェントには topic または url パラメーターが提示されないため、プロンプトインジェクションされた呼び出しによって、メッセージやトピック名（公開 ntfy.sh では実質的にパスワードです）が別の場所に送られることはありません（#21を参照）。
  • NTFY_TOPICS_ALLOWLIST=alerts,builds を設定すると、エージェントは実際に登録しているトピックと NTFY_TOPIC の中から選択できます。それ以外のトピックは選択できません（#34を参照）。ほかのトピックはリクエストを行う前に拒否され、黙って代替されることはありません。これらのトピック名（NTFY_TOPIC を含む）はツールスキーマに表示されるため、モデルと MCP クライアントから確認できます。許可リストがない場合、ツールスキーマにトピック名が含まれることはありません。公開 ntfy.sh ではトピック名はパスワードのように機能するため、共有しても問題ない名前、または保護されたトピックに限って許可リストを使用してください。
  • NTFY_ALLOW_TOPIC_OVERRIDE=true と NTFY_ALLOW_URL_OVERRIDE=true を設定すると、それぞれ独立して、任意のトピックまたはサーバーを再び指定できるようになります。NTFY_TOPICS_ALLOWLIST も設定されている場合は、NTFY_ALLOW_TOPIC_OVERRIDE よりも優先されます。
  • URL の上書きを有効にしていても、NTFY_TOKEN が送信されるのは NTFY_URL のサーバーだけです。呼び出し時に独自の accessToken が指定されない限り、ほかのサーバーには認証情報が送信されません。
• トークン： 共有する設定ファイルに NTFY_TOKEN を直接記述するのではなく、クライアントのシークレット入力（例：VS Code の ${input:…}）または環境変数を使用してください。

脆弱性を発見しましたか？ 公開 issue ではなく、GitHub のセキュリティアドバイザリーから非公開で報告してください。

開発と貢献

貢献を歓迎します！一般的なガイドラインやセットアップ手順などについては、CONTRIBUTING.mdを参照してください。

ライセンス

このプロジェクトは GNU General Public License v3.0 のもとでライセンスされています。詳細は LICENSE ファイルを参照してください。

❤️ を込めて gitmotion が作成