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 <npub> (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 <seconds>. 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 <bunker://…> 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",


... [View full README on GitHub](https://github.com/forgesworn/bray#readme)