# Bray

> Trust-aware Nostr for AI agents -- 235 tools covering social, DMs, zaps, trust, and identity

- **Type:** MCP server
- **Install:** `agentstack add mcp-forgesworn-bray`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [forgesworn](https://agentstack.voostack.com/s/forgesworn)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 1.27.7
- **License:** MIT
- **Upstream author:** [forgesworn](https://github.com/forgesworn)
- **Source:** https://github.com/forgesworn/bray
- **Website:** https://github.com/forgesworn/bray#readme

## Install

```sh
agentstack add mcp-forgesworn-bray
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# nostr-bray

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

[](https://www.npmjs.com/package/nostr-bray)
[](https://github.com/forgesworn/bray/actions/workflows/ci.yml)
[](./LICENSE)
[](./tsconfig.json)
[](https://github.com/sponsors/TheCryptoDonkey)

## Quick Start

Install globally or run via npx:

```bash
npm install -g nostr-bray
```

Add to your MCP client config:

```json
{
  "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](https://github.com/forgesworn/heartwood) or any NIP-46 bunker (your key never leaves your signing device):

```json
{
  "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** -- `"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 | 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`):

```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

```bash
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](./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

## For AI Assistants

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

## Part of the ForgeSworn Toolkit

[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.

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

## Licence

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [forgesworn](https://github.com/forgesworn)
- **Source:** [forgesworn/bray](https://github.com/forgesworn/bray)
- **License:** MIT
- **Homepage:** https://github.com/forgesworn/bray#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v1.27.7 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **1.27.7** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-forgesworn-bray
- Seller: https://agentstack.voostack.com/s/forgesworn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.