Ntfy MCP Server

---

概要

ntfy を通じてスマートフォンやデスクトップにプッシュ通知を送信します。通知の公開、更新、管理、トピックの最近の履歴の取得、タグ用の絵文字ショートコードの検索ができます。

ツール

ツール	説明
ntfy_publish_message	ntfy トピックにプッシュ通知を送信または更新します。
ntfy_manage_message	sequence_id を指定して、送信済みの通知を消去または削除します。
ntfy_fetch_messages	任意のフィルターを指定して、1 つ以上のトピックからキャッシュされたメッセージを取得します。
ntfy_search_emoji_tags	tags で使用する ntfy 絵文字タグのショートコードを検索します。

リソース

リソース	説明
ntfy://{topic}	トピックのスナップショット — 過去 1 時間の最新 20 件のメッセージと、トピックのブラウザー URL。

リソースの固定されたデフォルト設定では不十分な場合、ntfy_fetch_messages でカスタムの期間やフィルターを指定して同じトピックデータを取得できます。

機能リファレンス

ntfy_publish_message _ツール

• トピックは初回の公開時に作成されます。トピック名は秘密として扱ってください。名前を知っている人なら誰でも公開または購読できます
• title、priority（1～5）、tags、click、attach、icon、filename、markdown、delay、email、call、cache、firebase、および最大 3 個のアクションボタン（view、broadcast、http、copy）を受け取ります。本文は最大 4096 バイトで、空の場合はデフォルトで triggered になります。送信済みメッセージを更新するには、元の sequence_id を渡してください
• email、call、または broadcast／http ボタンを使って公開する場合は、送信前に対象をユーザーに確認します
• 呼び出しごとの base_url に認証情報が付与されるのは、登録済みサーバー（NTFY_BASE_URL または NTFY_SERVERS のエントリー）と一致する場合のみです。それ以外の場合、リクエストは認証されません

---

ntfy_manage_message _tool

• operation：clear は通知を既読にして閉じます（購読者には message_clear が表示されます）。delete は通知一覧から削除します（購読者には message_delete が表示されます）。
• 呼び出しごとに、最初にトピック、sequence_id、操作の確認をユーザーに求めます。確認を拒否すると consent_declined で失敗します。
• 元のメッセージはキャッシュに残り、同じ操作を繰り返しても問題ありません。ntfy.sh は不明な sequence_id を受け入れますが、より厳格なデプロイでは not_found が返されます。

---

ntfy_fetch_messages _tool

• ライブストリームではなくスナップショットを返します。カンマ区切りのトピック（例：alerts,backups）と、since（期間／タイムスタンプ／メッセージ ID／all／latest）、priority、tags、id、title、message、スケジュール済みのみ、によるフィルターを受け付けます。
• デフォルトの対象期間は 10m、デフォルトの上限は20件で、1回の呼び出しにつき最大100件です。対象期間を広げると、最新の limit 件が totalCount とともに返されます。nextCursor を cursor として渡すことで続きを取得できます。
• 本文は約500文字で切り詰められます（省略された文字数は messageTruncated で示されます）。全文を取得するには id を指定して再取得してください。
• ntfy が再生データを上限で切り詰めた場合は upstreamTruncated を設定し、サーバーが ntfy メッセージストリームを返さない場合は upstream_malformed で失敗します。

---

ntfy_search_emoji_tags _tool

• タグ名を大文字と小文字を区別せず部分一致で検索します。query を省略すると、参照リストを順番どおりに返します。
• limit のデフォルトは25件で、1回の呼び出しにつき最大200件です。totalCount を使い、offset でページを移動します。
• 返された tag 文字列は、そのまま ntfy_publish_message の tags に指定できます。
• デフォルトで有効です。NTFY_ENABLE_EMOJI_TAGS=false を設定すると、tools/list から削除されます。

---

ntfy://{topic} _resource

• 固定スナップショットです。過去1時間の最新20件のメッセージと、そのトピックのブラウザー URL を、ntfy_fetch_messages と同じ形式（upstreamTruncated を含む）で返します。
• 独自の対象期間やフィルターを指定する場合は、ntfy_fetch_messages を使用してください。

機能

@cyanheads/mcp-ts-core を基盤とし、stdio および Streamable HTTP トランスポート、切り替え可能な認証方式（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースを伴う構造化ロギングを備えています。

ntfy 固有の機能：

• ntfy クライアントは再試行に対応し、試行ごとのタイムアウトを設定できます。各呼び出しは最大50秒で打ち切られるため、MCP クライアントのデフォルトである60秒以内に処理が完了します。
• サーバーごとの認証：認証情報は登録された各ベース URL（NTFY_BASE_URL または NTFY_SERVERS のエントリ）に紐づきます。ベアラートークンとベーシック認証は相互排他的です。
• stdio と Streamable HTTP の両方で、clear／delete、または email、call、broadcast／http ボタンを含む publish の前に、ユーザーに確認を求めます。
• base_url の上書きに対するオプションの SSRF ガード（NTFY_BLOCK_PRIVATE_HOSTS）。登録済みサーバーは対象外です。
• 絵文字タグの参照データを同梱しています。上流の docs/ntfy/emojis.md から scripts/build-emoji-tags.ts を使って再生成されます。

エージェント向けの出力：

• publish と manage は解決済みのトピック、ID、タイムスタンプを返します。fetch は解決済みの since と適用されたフィルターも返します。
• 型付きの reason コード（consent_declined、forbidden_topic、rate_limited、not_found、payload_too_large など）により、呼び出し側は失敗の種類に応じて処理を分岐できます。
• fetch と絵文字検索は truncated、totalCount、次の手順（nextCursor を cursor として渡す、または offset を進める）を示す notice を返します。

はじめに

以下を MCP クライアントの設定ファイルに追加してください。公開 ntfy.sh はアカウントなしですぐに利用できます。保護されたトピックの場合は、https://ntfy.sh/account でアクセストークンを生成してください。

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NTFY_DEFAULT_TOPIC=your-topic-name",
        "ghcr.io/cyanheads/ntfy-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24+）。
• ntfy サーバー上のトピック名。公開 ntfy.sh はアカウント不要です。セルフホストのインスタンスや保護されたトピックでは、ベアラートークンまたはベーシック認証の認証情報が必要になる場合があります。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd ntfy-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)

設定

変数	説明	デフォルト
NTFY_SERVERS	{ baseUrl, authToken? | authUsername?+authPassword? } エントリの JSON 配列です。ntfy サーバーごとに 1 つのエントリを指定し、先頭のエントリがデフォルトになります。以下の単一サーバー用変数より優先されます。	—
NTFY_BASE_URL	単一サーバー用の省略形です。ntfy サーバーのベース URL（末尾にスラッシュを付けません）。NTFY_SERVERS が未設定の場合に使用されます。	https://ntfy.sh
NTFY_DEFAULT_TOPIC	ツール呼び出しで topic が省略された場合に使用するトピックです。	—
NTFY_AUTH_TOKEN	単一サーバー用の省略形で使う Bearer アクセストークン（tk_…）です。NTFY_AUTH_USERNAME / NTFY_AUTH_PASSWORD とは併用できません。	—
NTFY_AUTH_USERNAME	単一サーバー用の省略形で使う Basic 認証のユーザー名です。NTFY_AUTH_PASSWORD と併せて指定する必要があります。	—
NTFY_AUTH_PASSWORD	単一サーバー用の省略形で使う Basic 認証のパスワードです。NTFY_AUTH_USERNAME と併せて指定する必要があります。	—
NTFY_REQUEST_TIMEOUT_MS	1 回の試行に対する HTTP タイムアウト（ミリ秒）です。すべての試行を通じて、各呼び出しの上限も 50 秒です。	15000
NTFY_MAX_RETRIES	一時的なアップストリーム障害（5xx、ネットワーク、429）に対する最大再試行回数です。	3
NTFY_BLOCK_PRIVATE_HOSTS	true の場合、呼び出しごとの base_url オーバーライドはパブリックアドレスに解決される必要があり、リダイレクトは追跡されません。登録済みサーバーは対象外です。制御できない呼び出し元からサーバーにアクセスできる環境では有効にしてください。	false
NTFY_ENABLE_EMOJI_TAGS	false に設定すると ntfy_search_emoji_tags が無効になります。認識されない値が指定されると、起動に失敗します。	true
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_SESSION_MODE	HTTP セッションモデル：auto、stateful、または stateless。HTTP ではこのサーバーに stateful が必要です（auto はこれに解決されます）。起動時に stateless は拒否されます。stdio では無視されます。	stateful
MCP_HTTP_HOST	HTTP ホストです。	127.0.0.1
MCP_HTTP_PORT	HTTP ポートです。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパスです。	/mcp
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_REQUEST_STATE_KEY	HTTP での設定を推奨します。同意の requestState を 900 秒間封印するキー（32 バイト以上。例：openssl rand -base64 32。すべてのインスタンスで同じ値を使用してください）です。無効または期限切れの状態は -32602 invalid_request_state で拒否されます。	—
STORAGE_PROVIDER_TYPE	同意レコードの保存先（TTL は 600 秒）です。複数インスタンスの HTTP では共有ストレージが必要です。filesystem（共有ボリューム）、supabase、または cloudflare-d1 を使用し、cloudflare-kv は使用しないでください。	in-memory
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ファイルベースのログのディレクトリです（Node のみ。Workers では無視されます）。	./logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果をログに記録します。キー名に基づいて機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限とします。自由形式の値に含まれる機密情報はマスキングされません。	false
OTEL_ENABLED	OpenTelemetry instrumentation（スパン、メトリクス、完了ログ）を有効にします。	false

任意のオーバーライドの全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行します：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行します：

  bun run devcheck     # Lint, format, typecheck, security, changelog sync
  bun run test         # Vitest test suite
  bun run lint:mcp     # Validate MCP definitions against spec
  

Docker

docker build -t ntfy-mcp-server .
docker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server

Dockerfile はデフォルトで HTTP トランスポート、stateful セッションモードを使用し、/var/log/ntfy-mcp-server にログを記録します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サービスを初期化します。
src/config	Zod を使用した、サーバー固有の環境変数（NTFY_*）の解析です。
src/mcp-server/tools	ツールの定義（*.tool.ts）です。
src/mcp-server/resources	リソースの定義（*.resource.ts）です。
src/services/ntfy	ntfy の HTTP クライアント、型、エラー分類機能です。
src/services/emoji-tags	バンドルされた絵文字ショートコードのリファレンスと検索サービスです。
docs/ntfy	上流の ntfy API ドキュメントのミラーです（固定されたコミットは SOURCES.md に記載されています）。
tests/	src/ の構成を反映した単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジック内で try/catch を使用しないでください。
• リクエスト単位のロギングには ctx.log を、テナント単位のストレージには ctx.state を使用してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを決して捏造しないでください。
• ツールごとの errors[] コントラクトはインラインに保ちます。重複は局所性を保つための意図的なものです。

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。