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

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 -- "[email protected]" (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:

Configuration

Config file (recommended)

Create ~/.config/bray/config.json (or ~/.nostr/bray.json):

{
  "bunkerUriFile": "/Users/you/.nostr/bunker-uri",
  "relays": ["wss://relay.damus.io", "wss://nos.lol"],
  "trustMode": "annotate"
}

Secrets are referenced by file path (bunkerUriFile, secretKeyFile, nwcUriFile) so they never appear in the config itself.

trustMode is strict (hide content from untrusted pubkeys), annotate (show trust scores) or off (no filtering). The default is annotate; an unrecognised value falls back to annotate. The TRUST_MODE environment variable overrides the config file.

Search order: BRAY_CONFIG env var > $XDG_CONFIG_HOME/bray/config.json > ~/.nostr/bray.json.

Environment variables

All secret env vars are deleted from process.env before parsing can fail. Raw NWC_URI is refused; use NWC_URI_FILE or wallet connect <nwc-file> so the bearer credential never appears in a process environment, command argument or MCP tool argument. The wallet must speak NIP-44 v2 encryption for NWC; wallets that only offer NIP-04 are refused.

Keys this process must never be

An agent that comes up holding the wrong key is indistinguishable from one working correctly. Every signature verifies, every tool succeeds, and the only symptom is that whoami quietly answers with somebody else's npub — which the driving model has no reason to doubt, because it is its own tool telling it.

The worst version is a principal's key: a person's own. An agent signing as its principal can attest that it belongs to itself, and approve its own requests, because it is the principal those checks look for.

NOSTR_FORBID_PUBKEY=npub1yourownkey...,npub1anotherhuman...

or forbidPubkeys in the config file. Either takes npubs or hex. Activating one of those keys throws instead — at startup, on identity-switch, and on bunker --persona alike, because the check sits at the moment an identity becomes active rather than at any one entry point. An entry that cannot be parsed is an error too: a list nobody can read must not silently permit everything.

The active npub is printed on stderr on every start, so the answer to "which key is this?" does not depend on asking the agent.

Spending limits

The hard limit is the wallet's own. Point NWC_URI_FILE (or wallet connect <file>) at a connection your wallet issued with a spending budget. Whatever bray does, and whatever a model asks of it, the wallet will not pay past that budget. Everything below is bray policing itself, which is worth having but is not the same thing.

On top of that, every payment bray makes (zap-send, marketplace-pay, the CLI's zap-send and wallet pay, the SDK, and payments made through the scoped connections below) is checked before anything is sent:

• Per payment: at most BRAY_MAX_PAYMENT_MSAT (default 5,000 sats).
• Per day: at most BRAY_MAX_DAILY_MSAT in any rolling 24 hours (default

20,000 sats), counting a 1% (minimum 1 sat) fee reserve until the real fee is known. Attempts are written to payment-ledger.json in the state directory before the wallet is asked, so a restart does not hand the allowance back.

• Once per invoice: an invoice is never paid twice, and an attempt whose

outcome is unknown is only retried after a lookup shows it failed.

confirm: true is set by the model, so it is not a human approval. When your MCP client supports elicitation, zap-send and marketplace-pay also ask you directly and pay only on an explicit yes; clients without elicitation fall back to confirm, with the caps still applying. zap-send is not in the default tool list either: it is reached through search-actions.

Handing out a wallet connection

zap-send spends through the NWC URI you configured. That URI is an unbounded capability over the wallet behind it: every method it supports, no ceiling, until it is rotated. Handing one to an agent hands over everything.

wallet-grant issues scoped spending connections over that one wallet: one wallet, one balance, and several narrower ways in. They are not separate wallets. The tools that mint or widen spending authority (wallet-grant, wallet-refill, wallet-serve) are registered only with BRAY_WALLET_SERVICE=1; wallet-grants and wallet-revoke are always available.

wallet-grant   { name: "research-agent", methods: ["get_info","pay_invoice"],
                 budgetMsat: 50000, maxPaymentMsat: 5000 }
wallet-grants  # what exists, what it may do, what it has spent
wallet-revoke  { nameOrId: "research-agent" }
wallet-refill  { nameOrId: "research-agent", budgetMsat: 50000 }
wallet-serve   { action: "start" }

wallet-grant writes the new connection's nostr+walletconnect:// URI to a 0600 file under wallet-connections/ beside the grants file and returns the path; the URI itself never appears in a tool result.

What a connection may do is an allowlist, and the default grants no spending and does not disclose anything: get_info and make_invoice. The others are opt-in per connection, and a connection that can spend must carry a budget - there is no unlimited grant to issue by accident. A connection sees only itself:

• get_balance reports the connection's remaining budget, never the

wallet's balance.

• lookup_invoice answers only for invoices that connection issued or paid;

anything else is reported as not found.

The rules exist because a payment cannot be recalled:

• A request is answered once. Its id is persisted before the payment is

attempted, so a process that dies mid-payment comes back knowing not to try again - a relay will hand the same signed request over twice.

• Requests on one connection are serialised, so two arriving together

cannot both read the same remaining budget.

• A request older than five minutes is not answered, whatever its own

expiration tag claims.

• Each connection has its own service key: two grants share nothing a

relay can correlate, and revoking one is deleting a key.

• The budget is charged what the invoice says, decoded here, plus the

routing fee: a fee reserve is held until the wallet reports the real fee. Invoices that state no amount are refused. A budget checked against a figure the payer supplied is not a budget.

• A definite refusal from the wallet (insufficient balance, say) gives the

budget back, and the connection is not told why the wallet refused.

• bray's own per-payment and daily caps apply to these payments as well.
• A claimed payment whose preimage does not settle the invoice is refused

rather than passed on. Repeating an unproven claim would make this service the one telling the lie.

Grants live in wallet-grants.json (0600, per identity), and they are answered only while `wallet-serve` is running - which is to say, only for as long as this process is alive. That is worth telling whoever you hand a URI to: a connection that works while an MCP session is open is a different promise from one that works overnight.

The file is the record, shared by every bray process on the machine. Only one process may serve the grants at a time, the serving process re-reads a grant before every request, and every change is a locked update of the file, so a revocation or refill made from any process applies to the next request and cannot be written away by another.

CLI

npx nostr-bray whoami                    # show your npub
npx nostr-bray post "hello from bray!"   # publish a note
npx nostr-bray persona work              # derive a work persona
npx nostr-bray prove blind               # create a linkage proof
npx nostr-bray --help                    # see all commands

Use as a library

The package is also a TypeScript SDK (ESM only). nostr-bray/sdk is the factory API:

import { createBray } from "nostr-bray/sdk"

const bray = await createBray({
  sec: process.env.NOSTR_SECRET_KEY, // or bunkerUri: "bunker://..."
  relays: ["wss://relay.damus.io", "wss://nos.lol"],
})

await bray.post("gm nostr")
console.log(bray.npub)
bray.destroy() // zeroise key material

defaultBray() builds the same client from the environment variables above. The handlers behind each tool group are exported as subpaths, so you can import one group without the rest:

Documentation

• [Usage Guide](./docs/guide.md) -- walkthroughs for identity, DMs, attestations, payments, and duress
• [Examples](./examples/) -- MCP config files and CLI workflow scripts
• [Contributing](./CONTRIBUTING.md) -- setup, architecture, testing, and conventions
• [Privacy](./PRIVACY.md) -- what bray sends where (it runs on your machine; no telemetry)

For AI Assistants

See llms.txt for a concise summary optimised for AI context windows, or llms-full.txt for complete tool documentation with parameter details.

Part of the ForgeSworn Toolkit

ForgeSworn builds open-source cryptographic identity, payments, and coordination tools for Nostr.

Support

For issues and feature requests, see GitHub Issues.

If bray is useful to you, a tip is always welcome:

• Lightning: [email protected]
• Nostr zaps: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

Licence

MIT