A Model Context Protocol server that gives an AI assistant its own three.ws notification inbox + delivery control over stdio. Read inbound events (pump/market alerts, sales & earnings, purchase receipts, social mentions, IRL interactions, account/security), mark them read, tune the per-category → per-channel delivery matrix, and register Web Push devices — all live, all account-scoped.

Every read and write hits the real three.ws API. The server is authenticated: it carries a three.ws API key (or OAuth access token) as a Bearer credential and resolves the owning account on every call. It signs nothing locally and holds no other secret.

Install

npm install @three-ws/notifications-mcp

Or run with npx (no install):

npx @three-ws/notifications-mcp

Quick start

Claude Code, one line:

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

Tools

Tool Kind What it does
list_notifications read The inbox, newest first, filterable by type, with an unread_count.
mark_read write Mark one notification — or every unread one — read.
delete_notification write ⚠️ Permanently remove one notification (irreversible).
get_preferences read The per-category → per-channel delivery matrix (in_app, push, email, telegram).
set_preferences write Patch which channels deliver each category.
register_push_device write Register a Web Push device from a browser PushSubscription.
unregister_push_device write ⚠️ Remove a Web Push device (tears down delivery to it).

Configuration

Env var Required Default Description
THREE_WS_API_KEY yes — three.ws API key (sk_live_… / sk_test_…) or OAuth access token for the account. Aliases: THREE_WS_TOKEN, THREE_WS_BEARER. Treat like a password.
THREE_WS_BASE no https://three.ws API base URL. Override only when self-hosting or targeting a preview.
THREE_WS_TIMEOUT_MS no 20000 Per-request timeout in milliseconds.

Every endpoint is account-scoped and returns 401 without a valid credential — this server can never read or change another account.

License

All rights reserved. See LICENSE.