ntfy

ntfy-mcp

ntfy 用の Model Context Protocol（MCP）サーバーです。ntfy は、HTTP リクエストだけでスマートフォンにプッシュメッセージを送信する、パブリッシュ／サブスクライブ型の通知サービスです。

Claude Code、Claude Desktop、Codex などの MCP クライアントから通知を送信したり、送信済みの内容を読み返したり、ジョブの実行中に通知をその場で更新したりできます。また、管理者アカウントを使えば、アカウントの作成やトピックへのアクセス権の付与・取り消しも行えます。これらの操作は通常、サーバー上で ntfy コマンドラインを使って行います。

ツール数は13個が上限であり、最低数ではありません。NTFY_ALLOW_TOOLS=essential を設定すると、厳選された6個のツールだけを登録できます。13個より6個のほうが、モデルは適切なツールをはるかに確実に選択できます。詳しくは読み込むツールの選び方をご覧ください。

特長

進捗レポートが1つの通知にまとまります。 publish_message が返す ID は通知のシーケンス ID でもあります。update_message はその通知の内容をその場で置き換えるため、購読者には5つの通知が届くのではなく、1つの通知が「building」から「deployed」へと変化して見えます。

NTFY_TOPICS がアクセス範囲を制限します。 ntfy では、トピック名はベアラー認証情報です。その名前を知っているだけでアクセス制御のすべてとなることも珍しくありません。この変数には、このサーバーが操作できるトピックを指定し、ツールでトピックを省略した場合のデフォルトも設定します。そのため、トピック名をツールの引数やモデルのコンテキストに含めずに済みます。

要件

• Node.js ≥ 24
• 接続可能な ntfy サーバー。認証情報は任意です。匿名アクセスを許可するインスタンスであれば、認証情報は必要ありません。

設定

変数	必須	説明
NTFY_URL	はい	ベース URL。例：https://ntfy.example.net。意図的にデフォルト値はありません。https://ntfy.shを指定すると、設定ミスによって公開インターネットに公開される可能性があるためです。
NTFY_TOKEN	いいえ	アクセストークン（tk_…）。以下の2つとは同時に指定できません。
NTFY_USERNAME	いいえ	Basic 認証のユーザー名。NTFY_PASSWORDと併せて指定する必要があります。
NTFY_PASSWORD	いいえ	Basic 認証のパスワード。
NTFY_TOPICS	いいえ	このサーバーが使用できるトピックをカンマ区切りで指定します。先頭のトピックは、ツールでトピックが省略された場合のデフォルトになります。また、このリストはアクセス許可を含むすべてのツールの読み取りと書き込みを制限します。
NTFY_READ_ONLY	いいえ	true、1、またはyes（大文字と小文字は区別しません）を指定すると、読み取り専用の6つのツールのみを登録します。デフォルトはfalseです。
NTFY_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_*プレフィックス、または厳選されたプリセットを指定するessential
NTFY_DENY_TOOLS	いいえ	同じ構文を使用します。NTFY_ALLOW_TOOLSで残ったものから除外します。
NTFY_INSECURE_TLS	いいえ	trueを指定すると、自己署名証明書を受け入れます（この接続にのみ適用されます）。

NTFY_TOKENとNTFY_USERNAME／NTFY_PASSWORDを同時に設定すると、優先順位による解決は行わず、起動時に拒否されます。どの認証情報が有効なのかが曖昧になってはなりません。

https://を使用してください。 平文の http では認証情報が暗号化されずに送信されます。Basic 認証は Base64 であり、暗号化ではありません。また、ホストがローカルでない場合、サーバーは警告を出力します。自己署名証明書を使用する場合は、NTFY_INSECURE_TLSよりも、適切な内部 CA を使用してください。

設定がなくてもサーバーは起動し、ツールを一覧表示します（レジストリやインスペクターからの情報取得が可能です）。ただし、すべての呼び出しは API にアクセスする代わりに、セットアップ手順を示すエラーになります。

書き込みはデフォルトで有効です

NTFY_READ_ONLY のデフォルトは false です。ntfy はメッセージを公開するためのものであり、読み取り専用をデフォルトにすると、通知できない通知サーバーを提供することになります。これは、同じ変数のデフォルトが true である imap-mcp とは逆です。メールボックスはかけがえのないアーカイブだからです。

知っておくべき点は次のとおりです。

• タイプミスをしても、書き込みは許可されたままです。 true、1、yes は、いずれも大文字小文字を問わず読み取り専用として扱われます。保護スイッチは意図的に寛容に解析されます。しかし、NTFY_READ_ONLY=ture はそのいずれにも該当せず、デフォルトでは書き込みが許可されているため、書き込みツールが有効なままになります。imap-mcp では、この場合は書き込みが禁止されます。
• 明示しない限り、公開できるクライアントはインスタンス上のどこにでも公開できます。 公開は破壊的な操作ではないため、確認トークンでは防げません。制御するのは NTFY_TOPICS です。

無人運用には、次の設定がおすすめです。

NTFY_TOPICS=deploys                 # the server can only touch this topic
NTFY_ALLOW_TOOLS=essential          # or:
NTFY_DENY_TOOLS=delete_messages,create_user,delete_user,manage_user_access

セルフホストのインスタンスでは、必要なトピックだけに write-only アクセスできる専用の ntfy アカウントもサーバーに設定してください。

読み込むツールの選択

NTFY_ALLOW_TOOLS と NTFY_DENY_TOOLS には、カンマ区切りでツール名を指定します。末尾の * は、該当するファミリー全体に一致します。essential は、get_server_info、check_topic_access、publish_message、list_messages、get_message、update_message を含む厳選プリセットで、ツールリファレンスではそのように示されています。この6つのうち4つは読み取りツールなので、NTFY_READ_ONLY=true の場合もプリセットは役立ちます。

NTFY_ALLOW_TOOLS=essential
NTFY_ALLOW_TOOLS=publish_message,list_messages
NTFY_DENY_TOOLS=delete_*,create_user,manage_user_access

どのツールにも一致しないエントリがあると、起動時にその名前を示して処理が中断されます。そのため、タイプミスによってツールが気づかれないまま無効になることはありません。存在しないツールが環境変数に起因すると突き止めるのは困難です。フィルターされたツールは登録されないため、tools/list にも表示されず、tools/call からも認識されません。これは NTFY_READ_ONLY によって書き込みツールが無効になる場合と同じです。

このサーバーを複数同時に実行する場合は、もうひとつの選択肢が mcp-hub です。その /hub エンドポイントを使うと、各サーバーのツールが6つのメタツールに置き換わります。

インストール

Claude Code

claude mcp add ntfy-mcp -- npx -y @ni-c/ntfy-mcp

Claude Desktop

{
  "mcpServers": {
    "ntfy-mcp": {
      "command": "npx",
      "args": ["-y", "@ni-c/ntfy-mcp"],
      "env": {
        "NTFY_URL": "https://ntfy.example.net",
        "NTFY_TOKEN": "…",
        "NTFY_TOPICS": "deploys"
      }
    }
  }
}

Codex

[mcp_servers.ntfy-mcp]
command = "npx"
args = ["-y", "@ni-c/ntfy-mcp"]
env = { NTFY_URL = "https://ntfy.example.net", NTFY_TOKEN = "…", NTFY_TOPICS = "deploys" }

Docker

docker run -i --rm \
  -e NTFY_URL=https://ntfy.example.net -e NTFY_TOPICS=deploys \
  ghcr.io/ni-c/ntfy-mcp

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクター、ウェブ版 Claude、Cursor、LibreChat）は、mcp-hub 経由で ntfy-mcp に接続できます。ひとつのコンテナーで複数の stdio MCP サーバーを Streamable HTTP 経由で提供し、ひとつのパスワードによる OAuth 2.1 ログインと、OAuth に対応していないクライアント向けの長期有効トークンを利用できます。その /hub エンドポイントでは、すべてのサーバーが6つのメタツールを通じて利用できるため、モデルのコンテキストに N 個のサーバー分のツールスキーマを含めることなく、ひとつのコネクターですべてに接続できます。また、2つのプロトコル改訂版のどちらにも対応しているため、このサーバーが尋ねる質問は、経由先の相手に届きます。

/config/mcp.json は Claude Code の形式を使用するため、エントリにはすでに設定済みのものをそのまま使えます。

{
  "mcpServers": {
    "ntfy-mcp": {
      "command": "npx",
      "args": ["-y", "@ni-c/ntfy-mcp"],
      "env": {
        "NTFY_URL": "https://ntfy.example.net",
        "NTFY_TOKEN": "…",
        "NTFY_TOPICS": "alerts",
        "NTFY_ALLOW_TOOLS": "essential"
      },
      "denyTools": ["delete_messages"]
    }
  }
}

allowTools と denyTools は、ハブ独自のサーバーごとのフィルターであり、env 内の *_ALLOW_TOOLS とは異なります。この違いと、起こりがちな間違いについては、クライアントガイドをご覧ください。

ツール

* は essential プリセットを示します。

ツール	説明
list_messages *	1 つ以上のトピックのキャッシュ済みメッセージをフィルター付きで取得し、次の呼び出しに使うカーソルを取得します
get_message *	アクションボタンと添付ファイルを含む、メッセージ全体を取得します
check_topic_access *	認証情報でトピックを購読できるか確認します — 下記の注記を参照してください
get_server_info *	ヘルス状態、機能、使用状況、および管理ツールを試す価値があるかどうかを確認します
get_account	設定済みの認証情報の ID、ロール、制限、使用状況を取得します
list_users	すべてのアカウントと、トピックごとのアクセス許可を取得します（管理者向け）
publish_message *	1 つ以上のトピックに通知を送信します
update_message *	通知をその場で更新し、進捗報告を 1 件の通知に保ちます
mark_messages_read	購読者のデバイス上の通知を消去します
delete_messages 👤	通知を削除し、予約済みの通知をキャンセルします
create_user 👤	管理者以外のアカウントを作成します（管理者向け）
delete_user 👤	アカウントとそのアクセス許可を削除します（管理者向け）
manage_user_access 👤	トピックまたはパターンへのアクセスを許可、拒否、または取り消します（管理者向け）

👤 は MCP のエリシテーションを通じてユーザーに確認を求めます。クライアントでダイアログを表示できない場合は、2 回の呼び出しで行う confirm_token に切り替わります。

構造化出力

各ツールは outputSchema を宣言し、テキストブロックに加えて structuredContent も返すため、クライアントは文章を解析せずに結果を利用できます。

{
  "untrusted": true,
  "source": "ntfy",
  "topics": ["alerts"],
  "count": 2,
  "next_since": "TmkVCUCmDdWL",
  "messages": [{ "id": "TmkVCUCmDdWL", "topic": "alerts", "title": "…" }],
}

untrusted マーカーはテキスト内の文だけでなくフィールドとしても含まれます。そうしないと、構造化データ部分を読み取りテキストを無視するクライアントが、文脈のない投稿者の文章を受け取ってしまうためです。このマーカーは、他者が書いた内容を報告する 4 つのツール、list_messages、get_message、get_account、list_users に付与されています。get_server_info には付与されません。そのセクションはインスタンス自身の設定とカウンターだからです。

このサーバーが構築するフィールドは正確に記述されています。一方、ntfy からそのまま渡されるドキュメント（/v1/config、/v1/stats、投稿者の添付ファイルメタデータ）は、形状を固定しないオブジェクトとして宣言されています。データより厳格なスキーマが、より優れた契約になるわけではありません。SDK はすべての結果をスキーマに照らして検証するため、上流のリリースでフィールドが追加されると、予想外のフィールドが 1 つ表示されるのではなく、ツール全体が利用できなくなります。

ntfy に関する、意外に思われる 2 つのこと

トピックごとに読み取りと書き込みの権限は別々に付与されます。 書き込み専用の投稿トークンでは、自分が投稿するトピックをポーリングできません。これは障害ではなく、正しい設定です。check_topic_access が確認するのは 読み取り 側だけなので、ここで拒否されても投稿に失敗するとは限りません — ツールの結果にもその旨が示されます。

サーバー上のトピックを一覧表示する方法はありません。 トピックは誰かが投稿した時点で存在し、公開インスタンスではトピック名そのものがアクセス制御のすべてです。トピック名は秘密として扱ってください。既存のトピックが表示されるのは get_account と list_users だけです。

意図的に実装していない機能

• 公開済みメッセージからのメール送信や電話の発信。 ntfy はどちらにも対応していますが、モデルの出力に応じて任意の宛先へメールを送る MCP ツールは、挿入可能なコンテンツによって動かされるスパム中継になり、call は実際に課金される通話を発信します。
• アクセストークンの作成、読み取り、交換。 この種のエンドポイントはすべて有効な認証情報を返し、その後、会話の記録に残ることになります。
• ストリーミング購読（/sse、/ws、/raw）。ツール呼び出しはタイムアウト付きのリクエスト／レスポンスです。list_messages は同じデータを上限付きで返します。
• 添付ファイルのアップロード。 モデルのコンテキストを介して Base64 を使うか、このサーバーが扱うべきではないローカルファイルシステムを介することになります。実際の用途は URL を使う attach で対応できます。
• 予約、課金、ウェブプッシュ、メールおよび電話による認証、Matrix ゲートウェイ。GET /v1/account はこれらのいくつかも返しますが、get_account はこのサーバーのどのツールも使わないペイロードを渡さず、破棄します。

意図的に公開していない機能

トピックの列挙はありません — ntfy にそのような API はなく、ほかのどのサービスにもありません。トピックは誰かが公開して初めて存在し、デフォルトのアクセスルールを使うインスタンスでは、その名前自体がアクセス制御のすべてです。そのため、一覧エンドポイントは認証情報の一覧になってしまいます。get_account はアカウントが購読しているトピックを示し、list_users はトピックごとの権限を示します。この 2 つが正確な回答です。

安全性

• 人に通知するだけでなく、本人に確認を求めます。 クライアントが MCP のエリシテーションに対応している場合、delete_messages、delete_user、manage_user_access、create_user、update_message は、モデルが本人の代わりに回答できない実際のダイアログを表示します。対応していない場合は、対象を正確に示すフィンガープリントに紐づいた短命トークンにフォールバックし、誰かが承認したかのように見せず、その旨を伝えます。ある対象への確認で、別の対象や、より長いリストを処理することはできません。また、manage_user_access では、同じ 3 つの引数を異なる順序で指定した場合も処理できません。人への確認を求めるを参照してください。
• アクセスツールも NTFY_TOPICS の範囲内に制限されます。 manage_user_access は、* を含め、リストの範囲を超えるパターンを拒否します。権限付与は対象となるすべてのトピックへの永続的なアクセスであり、ワイルドカードを含むパターンを有限の許可リストで網羅することはできないためです。list_users は、許可されたトピックに対する各アカウントの権限のみを報告します。権限パターンはトピック名であり、トピック名は所持者にアクセスを許す認証情報だからです。
• 確認プロンプトに ntfy のコンテンツを引用することはありません。 そのテキストはモデルが読むため、トピック、件数、ユーザー名のみを示し、それ以外は含めません。また、create_user に渡されたパスワードも決して含めません。有効な認証情報なので、プロンプトにもトークンの紐付けにも含まれません。
• 返されるコンテンツには、信頼できないデータであることを明示します。 実際に信頼できないデータだからです。通知内のすべての内容は、そのトピックに公開できる人が書いたものです。
• get_account は拒否リストではなく許可リストに基づいて応答します。 ID、ロール、ティア、制限、使用量、各アクセストークンの メタデータ を報告し、それ以外の ntfy が返す情報はすべて破棄します。これには、ntfy が平文で返すトークン値だけでなく、電話番号、課金識別子、予約および購読のトピック名も含まれます。今後 ntfy が追加するキーも、ここを変更しなければ破棄されます。
• 呼び出し元が指定する URL は http または https でなければなりません。 click、icon、attach、アクションボタンの URL はサーバーではなく受信者のデバイスが開きます。また、ntfy は渡された URL をそのまま保存するため、javascript: URL も保存されます。
• 公開者が制御するすべてのフィールドには上限があります。 ntfy はメッセージ本文を 4096 バイトに制限しますが、タイトルやタグのリストには制限がないため、ここで上限を設けています。
• NTFY_READ_ONLY=true の場合、書き込みツールは登録されません。また、NTFY_DENY_TOOLS では同じ方針に沿って、より細かく制限できます。フィルターされたツールは構築されないため、呼び出し時に拒否されることはありません。

ドキュメント

ガイド全文、ツールリファレンス、セキュリティに関する注意事項は ntfy-mcp.ni-c.de（ソースは docs/）にあります。

開発

npm install
npm run build
npm run lint && npm run typecheck && npm run test:coverage

アーキテクチャ図とソーシャルカードは自動生成されます。docs/assets/architecture.source.svg または docs/assets/og.json を編集して npm run assets を実行してください。docs/public/ 内の生成済みファイルは編集しないでください。CI では npm run assets:check を実行し、差異がある場合は失敗します。

ドキュメントサイトには独自のマニフェストがあるため、そのツールチェーンがコンテナーイメージやテストマトリックスに混入することはありません。

cd docs && npm install && npm run build

リリース

リリースはタグに基づいて行われます。package.json のバージョンを更新し、CHANGELOG.md の [Unreleased] の内容を新しいバージョンの下に移動してコミットし、次を実行します。

git tag -s vX.Y.Z -m "vX.Y.Z"
git push origin main vX.Y.Z

リリースワークフローでは Trusted Publishing（OIDC、プロベナンス付き）を使って npm に公開し、マルチアーキテクチャのコンテナーイメージを GHCR にプッシュし、CHANGELOG の該当セクションから GitHub リリースを作成し、公式 MCP レジストリのエントリーを更新します。

コントリビューション

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。脆弱性については、公開 Issue ではなく非公開での報告をご利用ください。ポリシーは SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel