nostr-bray

Trust-aware Nostr MCP for AI and humans. 235 tools across 27 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.

Quick Start

Install globally or run via npx:

npm install -g nostr-bray

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

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

Auth tiers (best to worst)

| Tier | Method | Key exposure | |------|--------|-------------| | Heartwood | Dedicated signing appliance (BUNKER_URI) | 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. |

Tool Groups

| Group | Tools | Key examples | |-------|------:|--------------| | Identity | 16 | whoami, identity-derive-persona, identity-switch, identity-prove, nip05-lookup | | Social | 15 | social-post, social-reply, social-feed, contacts-follow, social-notifications | | Direct Messages | 4 | dm-send, dm-read, dm-conversation | | Trust | 22 | trust-attest, trust-ring-prove, trust-spoken-challenge, trust-attest-chain | | Dispatch | 13 | dispatch-send, dispatch-check, dispatch-reply, dispatch-capability-discover | | Relay | 13 | relay-query, relay-set, relay-discover, cast-spell, relay-health | | Moderation | 16 | label-create, list-mute, list-bookmark, list-followset-create, moderation-filter | | Marketplace | 16 | marketplace-discover, marketplace-call, listing-create, listing-search | | Safety | 14 | canary-session-create, canary-group-create, canary-duress-signal, safety-activate | | Blossom | 10 | blossom-upload, blossom-mirror, blossom-verify, blossom-repair | | Privacy | 10 | privacy-commit, privacy-prove-range, privacy-prove-age, privacy-publish-proof | | Zap | 9 | zap-send, zap-balance, zap-make-invoice, zap-decode | | Vault | 9 | vault-create, vault-encrypt, vault-share, vault-rotate | | Workflow | 7 | trust-score, verify-person, identity-setup, relay-health, feed-discover | | Signet | 7 | signet-badge, signet-vouch, signet-credentials, signet-challenge | | Communities | 5 | community-create, community-feed, community-post, community-approve | | Badges | 4 | badge-create, badge-award, badge-accept, badge-list | | Groups (NIP-29) | 4 | group-info, group-chat, group-send, group-members | | Articles | 3 | article-publish, article-read, article-list | | Calendar | 3 | calendar-create, calendar-read, calendar-rsvp | | Wiki | 3 | wiki-publish, wiki-read, wiki-list | | Search | 3 | search-notes, search-profiles, hashtag-feed | | Scheduling | 4 | post-schedule, post-queue-list, post-queue-cancel, publish-event | | Community NIPs | 2 | nip-publish, nip-read | | Utility | 19 | decode, encode-npub, nip44-encrypt, verify-event, tombstone | | Handler | 2 | handler-publish, handler-discover | | Catalog | 2 | search-actions, execute-action |

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

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:

| NIP | What | |-----|------| | NIP-01 | Events, signing, relay protocol | | NIP-02 | Follow lists | | NIP-05 | DNS identity (lookup, verify, relay hints) | | NIP-09 | Event deletion | | NIP-11 | Relay information | | NIP-17 | Private DMs (gift wrap, default) | | NIP-19 | bech32 encoding (npub, nsec, nprofile, nevent, naddr) | | NIP-23 | Long-form articles (kind 30023) | | NIP-29 | Group chat | | 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-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 | Lightning zaps | | NIP-58 | Badges | | NIP-65 | Relay list metadata | | NIP-72 | Communities | | NIP-78 | Application-specific data | | NIP-85 | Trust rankings | | NIP-89 | Recommended applications (dispatch capability discovery) | | NIP-96 | HTTP file storage (Blossom) | | NIP-99 | Classified listings | | NIP-A7 | Spells (kind 777 — cast saved queries) | | NIP-VA | Verifiable attestations (kind 31000) |

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.

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 | | NOSTR_RELAYS | Comma-separated relay URLs | | TOR_PROXY | SOCKS5h proxy for Tor | | NIP04_ENABLED | Set 1 to enable legacy NIP-04 DMs | | TRANSPORT | stdio (default) or http | | PORT | HTTP port (default 3000) |

All secret env vars are deleted from process.env immediately after parsing.

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

Documentation

• Usage Guide -- walkthroughs for identity, DMs, attestations, payments, and duress
• Examples -- MCP config files and CLI workflow scripts
• Contributing -- setup, architecture, testing, and conventions

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.

| Library | What it does | |---------|-------------| | nsec-tree | Deterministic sub-identity derivation | | ring-sig | SAG/LSAG ring signatures on secp256k1 | | range-proof | Pedersen commitment range proofs | | canary-kit | Coercion-resistant spoken verification | | spoken-token | Human-speakable verification tokens | | toll-booth | L402 payment middleware | | geohash-kit | Geohash toolkit with polygon coverage | | nostr-attestations | NIP-VA verifiable attestations | | dominion | Epoch-based encrypted access control | | nostr-veil | Privacy-preserving Web of Trust |

Licence

MIT