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.
Trust-aware Nostr for AI agents -- 235 tools covering social, DMs, zaps, trust, and identity
API key
NOSTR_SECRET_KEY, NOSTR_RELAYS, NWC_URI
Last checked
2026-11-08
Stars
—
Tools
—
Uptime
—
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):
Key never leaves the signing device. Supports nsec-tree derivation, per-client permissions, and device-backed attestations.
Software bunker
Any NIP-46 bunker (BUNKER_URI)
Key held by a separate process. Never seen by bray.
ncryptsec
NIP-49 encrypted key (NOSTR_NCRYPTSEC)
Key encrypted at rest, decrypted in memory at startup.
Key file
File path (NOSTR_SECRET_KEY_FILE)
Key on disk, read once, env var deleted.
Env var
Inline secret (NOSTR_SECRET_KEY)
Key visible in process environment. Use only for development.
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.
Dispatch lets AI agents collaborate over encrypted Nostr DMs. Any MCP-capable client can send structured tasks to other agents and receive results back.
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)
Relay-scoped groups, chat, forums, invitations and administration
NIP-32
Labels
NIP-40
Expiration tags
NIP-42
Relay auth
NIP-44
Encrypted payloads v2
NIP-45
Event counts
NIP-46
Nostr Connect (bunker)
NIP-47
Nostr Wallet Connect: pay BOLT-11 invoices, balance, invoices, and scoped spending connections over one wallet. NIP-44 v2 only
NIP-49
Private key encryption (ncryptsec)
NIP-50
Search
NIP-51
Lists (mute, pin, follow sets, bookmarks)
NIP-52
Calendar events
NIP-54
Wiki pages
NIP-57
Zap receipts (kind 9735) are read. bray pays BOLT-11 invoices over NIP-47 but does not build kind 9734 zap requests or resolve LNURL, so it cannot yet zap a profile or note by itself
NIP-58
Badges
NIP-65
Relay list metadata
NIP-72
Communities
NIP-77
Negentropy ID reconciliation with truthful REQ fallback
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
Variable
Description
BRAY_CONFIG
Path to config file
BUNKER_URI
NIP-46 bunker URL (safest)
BUNKER_URI_FILE
Path to bunker URI file
NOSTR_SECRET_KEY
nsec, hex, or BIP-39 mnemonic
NOSTR_SECRET_KEY_FILE
Path to secret key file
NOSTR_NCRYPTSEC
NIP-49 encrypted key
NOSTR_NCRYPTSEC_PASSWORD
Password for ncryptsec
NWC_URI_FILE
Path to a private 0600 file containing the NWC bearer URI
BRAY_MAX_PAYMENT_MSAT
bray's ceiling on any one payment, in msat (default 5000000, 5,000 sats)
BRAY_MAX_DAILY_MSAT
bray's ceiling on spending in any rolling 24 hours, in msat (default 20000000, 20,000 sats)
BRAY_WALLET_SERVICE
Set 1 to register wallet-grant, wallet-refill and wallet-serve
DISPATCH_IDENTITIES
Path to the dispatch identities markdown table (name and hex pubkey). The dispatch tools are registered only when this is set; dispatchIdentities in the config file does the same
BRAY_HOME
Directory for bray's state files (default $XDG_CONFIG_HOME/bray, else ~/.config/bray)
NOSTR_RELAYS
Comma-separated relay URLs
NOSTR_FORBID_PUBKEY
Comma-separated npubs or hex this process must never sign as. See below.
TOR_PROXY
SOCKS5h proxy for Tor
NIP04_ENABLED
Set 1 to enable legacy NIP-04 DMs
TRUST_MODE
strict, annotate (default) or off. See the config file section above
TRANSPORT
stdio (default) or http
PORT
HTTP port (default 3000)
BIND_ADDRESS
HTTP bind address (default 127.0.0.1)
BRAY_HTTP_TOKEN
Bearer token the HTTP transport requires in the Authorization header. If unset, bray generates a random token and prints it once on stderr; a token you supply is never echoed
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.
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:
Import
What it gives you
nostr-bray
createBray, defaultBray and the handlers of every group below, re-exported
nostr-bray/sdk
createBray and defaultBray, the BrayClient factory API
nostr-bray/types
Type-only exports of the public config and result types
