three.ws Notifications

@three-ws/notifications-mcp

あらゆる AI エージェントから、three.ws の通知受信トレイ、配信設定、Web Push デバイスを利用できます。

インストール · クイックスタート · ツール · 認証 · エラー · three.ws

---

stdio 経由で AI アシスタントに専用の three.ws 通知受信トレイ＋配信制御を提供する、Model Context Protocol サーバーです。受信イベント（ポンプ／市場アラート、売上と収益、購入レシート、ソーシャルメンション、IRL インタラクション、アカウント／セキュリティ通知）の確認、既読への変更、カテゴリごと・チャネルごとの配信マトリクスの調整、Web Push デバイスの登録をすべてリアルタイムに、アカウントの範囲内で行えます。

理由

取引をしたり、スキルを販売したり、現実世界で活動したりするエージェントは、昼夜を問わず受信イベントを生成します。ローンチしたコインが急騰したり、公開したスキルが売れたり、誰かがエージェントの IRL ピンをタップしたりします。受信トレイがなければ、エージェントは多数のエンドポイントをポーリングするか、すべての通知を見逃してしまいます。このサーバーは、プラットフォーム独自の通知フィードを 7 つの MCP ツールとして提供します。エージェントは前回確認してから発生したことを読み取り、トリアージし、イベントカテゴリごとにどのチャネル（in_app、push、email、telegram）で所有者に通知するかを正確に制御できます。

すべての読み取りと書き込みで、実際の three.ws API にアクセスします。このサーバーは認証済みです。three.ws API キー（または OAuth アクセストークン）を Bearer 認証情報として使用し、呼び出しのたびに所有アカウントを解決します。ローカルで署名を行わず、その他のシークレットも保持しません。

インストール

npm install @three-ws/notifications-mcp

または、インストールせずに npx で実行できます。

THREE_WS_API_KEY=sk_live_… npx @three-ws/notifications-mcp

Node 20 以降が必要です。実行時の依存関係は 2 つ（@modelcontextprotocol/sdk、zod）です。

クイックスタート

Claude Code の場合は 1 行で設定できます。

claude mcp add notifications -e THREE_WS_API_KEY=sk_live_… -- npx -y @three-ws/notifications-mcp

Claude Desktop／Cursor／任意の MCP クライアント — MCP 設定（claude_desktop_config.json、.cursor/mcp.json、.mcp.json）に追加します。

{
	"mcpServers": {
		"notifications": {
			"command": "npx",
			"args": ["-y", "@three-ws/notifications-mcp"],
			"env": { "THREE_WS_API_KEY": "sk_live_…" }
		}
	}
}

クライアントを再起動すると、7 つのツールが表示されます。GUI でツールの一覧を確認できます。

npx -y @modelcontextprotocol/inspector npx -y @three-ws/notifications-mcp

次に、自然な言葉で指示します。

受信トレイに新着はありますか？ポンプアラートを既読にして、ソーシャルメンションのメール通知をオフにしてください。

list_notifications → mark_read → set_preferences の順に実行されます。

ツール

ツール	種類	内容
list_notifications	読み取り	受信箱を新しい順に表示します。type で絞り込め、unread_count も確認できます。
mark_read	書き込み	1 件または未読のすべての通知を既読にします。冪等です。
delete_notification	書き込み ⚠️	1 件の通知を完全に削除します（元に戻せません）。
get_preferences	読み取り	カテゴリごとのチャネル配信設定を確認します。
set_preferences	書き込み	各カテゴリをどのチャネルで配信するかを変更します。冪等です。
register_push_device	書き込み	ブラウザーの PushSubscription から Web Push デバイスを登録します。冪等です。
unregister_push_device	書き込み ⚠️	Web Push デバイスを削除します（そのデバイスへの配信を停止します）。冪等です。

各ツールには MCP ツールアノテーションが付属しています。2 つの読み取りツールは readOnlyHint: true を示し、2 つの ⚠️ ツールには destructiveHint: true のフラグが付いているため、アノテーションに対応したクライアントは実行前に確認を求めます。

list_notifications

アカウントの受信箱、つまりプラットフォームが配信する受信イベントフィードを読み取ります。対象は市場／ポンプ関連のアラート、販売と収益、購入レシート、ソーシャルメンション、IRL でのやり取り、アカウント／セキュリティに関する通知です。GET /api/notifications を呼び出します。

引数	型	必須	説明
type	string	いいえ	1 種類の通知のみを返します（例："pump_alert"、"skill_purchased"、"referral_earned"、"security_alert"）。lower_snake_case 形式で、40 文字以下です。すべての種類を対象にする場合は省略します。
limit	number	いいえ	返す件数です。新しい順に並びます。1～50 件で、既定値は 20 です。

呼び出しと応答の例（形式の説明です。実際の受信箱の内容は異なります）：

// call
{ "type": "pump_alert", "limit": 2 }

// response (example)
{
  "ok": true,
  "type": "pump_alert",
  "unread_count": 5,
  "count": 2,
  "notifications": [
    {
      "id": "5d1c2f0a-9b1e-4c3d-8e7f-000000000001",
      "type": "pump_alert",
      "payload": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "symbol": "THREE" },
      "read": false,
      "read_at": null,
      "created_at": "2026-07-11T18:04:12.000Z"
    }
  ]
}

read は read_at から導出されます（null ⇒ 未読）。unread_count はこのページだけでなく、受信箱全体の未読件数です。

mark_read

通知を既読にします。POST /api/notifications/:id/read（1 件）と POST /api/notifications/read-all（すべて）を呼び出します。2 つの引数のうちいずれか一方だけを指定してください。既読にすると read_at のみが設定され、削除はされません。また、再実行しても何も起こりません。

引数	型	必須	説明
id	string (UUID)	いずれか一方	既読にする単一の通知です（list_notifications から取得）。
all	boolean	いずれか一方	true ⇒ 未読の通知をすべて既読にします。

// call
{ "all": true }

// response (example)
{ "ok": true, "scope": "all", "marked_read": 5 }

id を指定した場合、応答は { "ok": true, "scope": "one", "id": "…", "read_at": "…" } です。

delete_notification

1 件の通知を完全に削除します。DELETE /api/notifications/:id を呼び出します。元に戻せないため、通常の通知整理には mark_read を使用してください。呼び出し元が所有する通知のみ削除できます。通知が見つからない場合、またはすでに削除されている id を指定した場合は、見つからないことを示すエラーが返されます。

引数	型	必須	説明
id	string (UUID)	はい	削除する通知です（list_notifications から取得）。

// call
{ "id": "5d1c2f0a-9b1e-4c3d-8e7f-000000000001" }

// response (example)
{ "ok": true, "id": "5d1c2f0a-9b1e-4c3d-8e7f-000000000001", "deleted": true }

get_preferences

解決済みの配信設定を読み取ります。各カテゴリについて、配信に使われるチャネルを確認できます。引数はありません。GET /api/notifications/preferences を呼び出します。実際の現在の状態に基づいて変更できるよう、set_preferences の前にこれを読み取ってください。

// response (example)
{
  "ok": true,
  "categories": [
    { "key": "sales", "label": "Sales & earnings", "description": "…" },
    { "key": "alerts", "label": "Market & pump alerts", "description": "…" }
    /* purchases, social, irl, account … */
  ],
  "channels": ["in_app", "push", "email", "telegram"],
  "prefs": {
    "categories": { "alerts": { "in_app": true, "push": true, "email": false, "telegram": false } },
    "telegram_chat_id": null
  },
  "push": { "subscribed_devices": 1 }
}

7 つのカテゴリは sales、purchases、social、irl、alerts、creations、account です。4 つのチャネルは in_app、push、email、telegram です。prefs.categories は、ユーザーが設定した一部の上書きをプラットフォームの既定値にマージした、有効な設定です。カテゴリには lockedChannels が含まれる場合もあります。account では in_app が有効に固定されているため、セキュリティや出金に関する通知は常にベルの受信箱に届きます。

set_preferences

配信マトリクスを部分更新します。PUT /api/notifications/preferences を呼び出します。2 つの引数のうち、少なくとも 1 つを指定してください。指定したカテゴリとチャンネルの組み合わせだけが変更されます。不明なキーはサーバー側で破棄され、変更していない組み合わせは現在の値を維持します。同じ値を再適用しても変更はありません。

引数	型	必須	備考
categories	object	少なくとも 1 つ	外側のキー：sales、purchases、social、irl、alerts、creations、account。内側のキー：in_app、push、email、telegram → 真偽値。account の in_app は常に有効で、false を指定しても無視されます。
telegram_chat_id	string	少なくとも 1 つ	telegram チャンネルの配信先となる数値の Telegram チャット ID。リンク解除するには "" を指定します。24 文字以下。

// call — stop emailing social mentions, push pump alerts
{ "categories": { "social": { "email": false }, "alerts": { "push": true } } }

// response (example) — the full resolved matrix after the update
{ "ok": true, "prefs": { "categories": { "social": { "email": false /* … */ } }, "telegram_chat_id": null } }

register_push_device

Web Push デバイスを登録し、そのデバイスでアカウントのプッシュ通知を受け取れるようにします。POST /api/push/subscribe を呼び出します。subscription 引数には、ブラウザーの pushManager.subscribe().toJSON() が返す値をそのまま指定してください。プッシュエンドポイントは全体で一意です。同じデバイスを再登録するとアップサートされます（最新の所有者が有効になります）。そのため、この操作は冪等です。カテゴリのプッシュ配信が実際に行われるかどうかは、引き続き set_preferences によって決まります。

引数	型	必須	備考
subscription	object	はい	{ endpoint, keys: { p256dh, auth } } — endpoint はプッシュサービスの URL（2048 文字以下）です。p256dh／auth はブラウザーから取得した Base64 URL エンコード済みのキーです。

// call
{
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/exampleSubscriptionId",
    "keys": { "p256dh": "BNcRd…", "auth": "tBHI…" }
  }
}

// response (example)
{ "ok": true, "registered": true, "endpoint": "https://fcm.googleapis.com/fcm/send/exampleSubscriptionId" }

unregister_push_device

Web Push デバイスを削除し、そのデバイスへのプッシュ通知を停止します。DELETE /api/push/subscribe を呼び出します。2 つの引数のうち、少なくとも 1 つを指定してください。デバイスの特定にはエンドポイントを使用します。冪等な操作です。登録されていないエンドポイントを削除しても ok が返されます。変更されるのは、そのデバイスへのプッシュ配信だけです。in_app、email、telegram の設定は変更されません。

引数	型	必須	備考
endpoint	string（URL）	いずれか 1 つ	削除するデバイスのプッシュエンドポイント URL（推奨）。
subscription	object	いずれか 1 つ	代わりにサブスクリプションオブジェクト全体を指定できます。その endpoint が使用されます。

// call
{ "endpoint": "https://fcm.googleapis.com/fcm/send/exampleSubscriptionId" }

// response (example)
{ "ok": true, "unregistered": true, "endpoint": "https://fcm.googleapis.com/fcm/send/exampleSubscriptionId" }

認証

すべてのエンドポイントはアカウント単位で処理され、有効な認証情報がない場合は 401 を返します。このサーバーが別のアカウントを読み取ったり変更したりすることはありません。

THREE_WS_API_KEY には次のいずれかを設定します。

• three.ws API キー（sk_live_…／sk_test_…）— three.ws ダッシュボードで作成できます。または
• アカウントの OAuth アクセストークン。

どちらも、すべてのリクエストで Authorization: Bearer … として送信されます。サーバー側では Bearer 認証が CSRF の対象外となるため、書き込みに追加のトークンは必要ありません。THREE_WS_TOKEN と THREE_WS_BEARER も別名として使用できます。認証情報はパスワードと同様に取り扱ってください。アカウントの受信トレイと配信設定に対する読み取り・書き込みの完全な権限が付与されます。

設定

環境変数	必須	デフォルト	説明
THREE_WS_API_KEY	はい	—	three.ws API キーまたは OAuth アクセストークン（認証を参照）。別名：THREE_WS_TOKEN、THREE_WS_BEARER。
THREE_WS_BASE	いいえ	https://three.ws	API のベース URL。セルフホストする場合、またはプレビュー環境を対象とする場合にのみ上書きしてください。
THREE_WS_TIMEOUT_MS	いいえ	20000	リクエストごとのタイムアウト（ミリ秒）。正の数を指定してください。

認証情報の確認はツールの実行時に行われます。認証情報がなくてもサーバーは起動し、ツール一覧を公開するため、tools/list は常に使用できます。

エラー

ツール呼び出しに失敗すると、MCP エラー結果（isError: true）が返されます。そのテキストは、単一の JSON オブジェクトです。

// error shape (example)
{ "ok": false, "error": "upstream_error", "message": "Not found", "status": 404, "detail": { /* API body */ } }

error	HTTP	意味	対処方法
missing_credential	401	THREE_WS_API_KEY（またはエイリアス）が設定されていません。	環境変数を設定し、クライアントを再起動してください。
validation_error	400	引数が無効です（例：mark_read に id も all も指定されていません）。	呼び出しを修正してください。不足しているものはメッセージに正確に示されています。
upstream_error	as returned	three.ws API がリクエストを拒否しました。status と detail に実際のレスポンス（401：キーが無効、404：不明な ID、429：レート制限）が格納されています。	status に応じて対処してください。429 の場合は、少し待ってから安全に再試行できます。
timeout	—	THREE_WS_TIMEOUT_MS 内に応答がありませんでした。	再試行してください。繰り返し発生する場合は、タイムアウトを延長してください。
network_error	—	リクエストが API に到達しませんでした（DNS、オフライン）。	接続状況と THREE_WS_BASE を確認してください。

読み取りは常に安全に再試行できます。書き込みは設計上冪等です（mark_read、set_preferences、register_push_device、unregister_push_device は再実行しても同じ状態になります）。冪等でないのは delete_notification のみで、繰り返し実行すると not-found が返されます。

関連項目

• @three-ws/brain-mcp — MCP を介した、three.ws のマルチプロバイダー LLM ルーターです。
• @three-ws/pumpfun-mcp — 無料の読み取り専用 pump.fun + Solana データです（多くの pump_alert イベントのソースです）。
• @three-ws/irl — インタラクションが irl カテゴリに記録される、現実世界でのプレゼンスレイヤーです。

リンク

• ホームページ：https://three.ws
• 変更履歴：https://three.ws/changelog
• 課題：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0。LICENSE を参照してください。

---

_{three.ws SDK スイートの一部 — 3D AI エージェント、オンチェーン ID、エージェント決済。
ウェブサイト · 変更履歴 · GitHub}