Bray

nostr-bray

Trust-aware Nostr MCP server, CLI and TypeScript SDK for AI and humans. 261 tools across 29 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.

Quick Start

Requires Node.js 24 or later.

Install globally or run via npx:

npm install -g nostr-bray

New to Nostr? Mint a key first -- this works before anything is configured and prints your npub plus a 24-word mnemonic (write it down; it is the key):

npx nostr-bray create

Add to your MCP client config:

{

"mcpServers": { "nostr": { "command": "npx", "args": ["nostr-bray"], "env": { "NOSTR_SECRET_KEY": "nsec1...", "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol" } } } }

npx nostr-bray with no arguments starts the MCP server (stdio by default, HTTP with TRANSPORT=http); subcommands run the CLI.

Then ask your AI to call whoami to verify it works.

For production use, prefer Heartwood or any NIP-46 bunker (your key never leaves your signing device):

{

"mcpServers": { "nostr": { "command": "npx", "args": ["nostr-bray"], "env": { "BUNKER_URI": "bunker://...", "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol" } } } }

Pair with a signer app (nostrconnect://)

If your signer is an app such as Amber or nsec.app, let bray start the pairing instead of copying a bunker:// URI out of it:

npx nostr-bray bunker pair --relay wss://relay.nsec.app

bray prints a nostrconnect:// URI. Paste or scan it into the signer app and approve. bray shows the account the signer will sign as and asks you to confirm it, then saves the signer, and the MCP server, CLI and SDK (defaultBray()) sign through it with no BUNKER_URI or key in your config.

Treat the URI as a one-time credential: whoever answers it first becomes the signer bray uses, so do not paste it into a chat or leave it on a shared screen. Outside a terminal, pass --expect (the account you mean to sign as) or --yes. bunker status shows whether the saved signer was paired. If the app later forgets bray, run bunker pair again. With TOR_PROXY set, pairing goes through the proxy and accepts only .onion relays unless ALLOW_CLEARNET_WITH_TOR=1. Pick a relay your signer app can reach; --relay can be repeated; without it bray uses NOSTR_RELAYS, then the relays in your config file. bray waits up to five minutes for the signer to answer, or --timeout . The pairing secret is single-use and is not saved. A BUNKER_URI or key you configure still takes precedence over the saved signer, and bunker connect replaces it.

Read-only (no key)

Start the MCP server with no key or bunker and it runs read-only: it holds no signer and loads no wallet, so it cannot post, sign, send or read DMs, decrypt or pay. Only lookup tools are offered (feeds, profiles, search, relay and trust checks), and asking for anything else returns an error saying bray is read-only. Set NOSTR_PUBKEY to an npub to read from that account's perspective, for example its notifications. Set BRAY_READ_ONLY=1 to force this mode even when a key or bunker is configured; a key file is then never opened. The CLI and SDK still require a signer.

{

"mcpServers": { "nostr": { "command": "npx", "args": ["nostr-bray"], "env": { "NOSTR_PUBKEY": "npub1...", "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol" } } } }

Auth tiers (best to worst)

Promoted tools

Of the 261 registered tools, 50 are promoted: callable directly from the MCP tool list. Everything else is catalogued, so find it with search-actions and run it with execute-action (both are always available). Nothing that spends is promoted.

• Identity and social: whoami, identity-switch, social-post, social-reply, social-feed, social-profile-get, dm-send, dm-read, dm-conversation
• Wallet, relay and trust: zap-balance, relay-query, signet-badge, trust-score, verify-person, vault-read
• Publishing: article-publish, article-read, article-list, search-notes, search-profiles, hashtag-feed
• Badges, communities and calendar: badge-create, badge-award, badge-accept, badge-list, community-create, community-feed, community-post, community-approve, community-list, calendar-create, calendar-read, calendar-rsvp
• Listings: listing-create, listing-read, listing-search, listing-close
• Dispatch (13): dispatch-send, dispatch-check, dispatch-reply, dispatch-ack, dispatch-status, dispatch-cancel, dispatch-refuse, dispatch-failure, dispatch-query, dispatch-propose, dispatch-capability-publish, dispatch-capability-discover, dispatch-capability-read

The dispatch tools are registered only when DISPATCH_IDENTITIES points at an identities file; without it 37 tools are promoted.

Tool Groups

Use search-actions to find tools by keyword, then execute-action to run them.

Protocol foundations: semantic event validation, NIP-77 reconciliation, and relay-scoped NIP-29 groups.

Dispatch: AI-to-AI Collaboration

Dispatch lets AI agents collaborate over encrypted Nostr DMs. Any MCP-capable client can send structured tasks to other agents and receive results back.

13 message types: send, check, reply, ack, status, cancel, refuse, failure, query, propose, capability-publish, capability-discover, capability-read.

NIP-89 capability discovery: Agents publish what they can do. Other agents discover capabilities by topic, then route tasks to the right collaborator automatically.

dispatch-send("alice", "think", "Analyse the trade-offs of NIP-44 vs NIP-04")

dispatch-check() → inbox with pending tasks dispatch-reply(taskId, result) → send results back encrypted

All messages are NIP-44 encrypted. Recipients are resolved by name, NIP-05, npub, or hex.

Identity Resolver

Every tool that accepts a recipient uses universal identity resolution. You never need to look up hex pubkeys manually.

Accepted formats:

• Name -- "alice" (resolved from your dispatch contacts)
• NIP-05 -- "alice@example.com" (HTTP lookup)
• npub -- "npub1abc..." (NIP-19 decode)
• Hex -- "a1b2c3..." (64-character passthrough)

Scheduled Posting

Sign events now, publish later. Events are signed immediately with your current key, then held in a queue until the scheduled time.

post-schedule("Good morning!", "2026-04-01T08:00:00Z")

post-queue-list() → view pending scheduled posts post-queue-cancel(id) → cancel before it publishes

NIP Coverage

nostr-bray implements or integrates the following NIPs:

| NIP-51 | Lists (mute, pin, follow sets, bookma