three.ws Notifications

@three-ws/notifications-mcp

通过任意 AI Agent 查看你的 three.ws 通知收件箱、投递偏好和 Web Push 设备。

安装 · 快速开始 · 工具 · 身份验证 · 错误 · three.ws

---

一个通过 stdio 为 AI 助手提供专属 three.ws 通知收件箱和投递控制的 Model Context Protocol 服务。读取收到的事件（泵涨／市场提醒、销售和收益、购买收据、社交提及、现实生活互动、账户／安全通知）、将其标记为已读、调整按类别 → 按渠道划分的投递矩阵，并注册 Web Push 设备——所有操作实时生效，且仅限当前账户。

为什么需要

交易、销售技能或在现实世界中活动的 Agent 会全天候产生收到的事件——它发行的币大涨了，它发布的技能售出了，有人点击了它的现实生活定位点。如果没有收件箱界面，Agent 就得轮询十几个端点，或者错过所有通知。此服务将平台自身的通知流转化为七个 MCP 工具：Agent 可以读取上次查看后发生的事件，对其分类处理，并精确控制每类事件使用哪些渠道（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+。两个运行时依赖（@modelcontextprotocol/sdk、zod）。

快速开始

Claude Code，一行命令：

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_…" }
		}
	}
}

重启客户端后，七个工具就会出现。也可以在图形界面中查看工具：

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

然后用自然语言提问：

我的收件箱里有什么新消息？将泵涨提醒标记为已读，并关闭社交提及的电子邮件通知。

依次运行 list_notifications → mark_read → set_preferences。

工具

工具	类型	功能
list_notifications	读取	收件箱，按时间从新到旧排列，可按 type 筛选，并包含 unread_count。
mark_read	写入	将一条或所有未读通知标记为已读。幂等。
delete_notification	写入 ⚠️	永久删除一条通知（不可撤销）。
get_preferences	读取	按类别 → 按渠道的投递矩阵。
set_preferences	写入	更新各类别使用哪些渠道投递。幂等。
register_push_device	写入	从浏览器的 PushSubscription 注册 Web Push 设备。幂等。
unregister_push_device	写入 ⚠️	移除 Web Push 设备（停止向其投递）。幂等。

每个工具都提供 MCP 工具注解：两个读取工具声明了 readOnlyHint: true，两个 ⚠️ 工具标记了 destructiveHint: true，因此支持注解的客户端会在执行前提示用户。

list_notifications

读取账户的收件箱——平台投递的入站事件信息流：市场／pump 提醒、销售与收益、购买收据、社交提及、线下互动，以及账户／安全通知。封装 GET /api/notifications。

参数	类型	必需	说明
type	string	否	仅返回一种通知类型（例如 "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（单条）和 POST /api/notifications/read-all（全部）。传入两个参数中的恰好一个。标记为已读只会设置 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

永久删除一条通知。封装 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 }
}

七个类别为 sales、purchases、social、irl、alerts、creations、account；四个渠道为 in_app、push、email、telegram。prefs.categories 是生效矩阵，其中已将用户的稀疏覆盖项合并到平台默认值中。类别还可能包含 lockedChannels：account 会锁定 in_app 为开启状态，因此安全和提现通知始终会送达铃铛收件箱。

set_preferences

更新通知矩阵。封装 PUT /api/notifications/preferences。必须至少提供两个参数中的一个。只会更改你传入的类别／渠道组合；未知键会在服务端丢弃；未触及的组合保持当前值。重复应用相同的值不会产生任何变化。

Arg	Type	Required	Notes
categories	object	至少一个	外层键：sales、purchases、social、irl、alerts、creations、account。内层键：in_app、push、email、telegram → 布尔值。account 的 in_app 已锁定为开启，传入 false 会被忽略。
telegram_chat_id	string	至少一个	用于接收 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() 返回值完全一致。Push 端点全局唯一——重新注册同一设备会执行 upsert（最新所有者生效），因此该操作具有幂等性。某个类别是否实际通过 push 渠道投递，仍由 set_preferences 控制。

Arg	Type	Required	Notes
subscription	object	是	{ endpoint, keys: { p256dh, auth } } — endpoint 是推送服务 URL（不超过 2048 个字符）；p256dh／auth 是浏览器提供的 base64url 编码密钥。

// 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。必须至少提供两个参数中的一个——通过端点定位设备。此操作具有幂等性：即使移除的端点未注册，也会返回 ok。只会影响向该设备投递 push；in_app、email 和 telegram 偏好设置不受影响。

Arg	Type	Required	Notes
endpoint	string (URL)	二选一	要移除设备的 push 端点 URL（优先使用）。
subscription	object	二选一	也可以提供完整的订阅对象；系统会使用其中的 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 作为别名。请像对待密码一样妥善保管凭据——它授予对账号收件箱和投递设置的完整读写权限。

配置

Env var	Required	Default	Description
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	按返回值	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 不具备幂等性，重复调用只会返回未找到。

相关项目

• @three-ws/brain-mcp — 通过 MCP 接入的 three.ws 多提供商大模型路由器。
• @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 Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}