nostrclaw

Leer en español: README.es.md

An MCP server that lets Claude analyse a Nostr relay: is it healthy, what does it advertise, what is going through it, and which keys look suspicious or automated, who vouches for them, and who is interacting with a note. By default it is read-only. Optionally (off until you enable it) Claude can also draft and publish notes, replies and reactions, and delete your own events through a remote signer (NIP-46: Clave, nsec.app, a bunker) — your private key never reaches this program and every publication needs your explicit confirmation. See Publishing and docs/signing-design.md.

Written in TypeScript on the official MCP SDK and nostr-tools. It runs locally over stdio (Claude Code, Claude Desktop) and talks to the relays you allow, nothing else.

0.14.0: the trust score's level now comes from the trusted keys' network only (a trusted key or 3+ keys they follow follow it → established; one → some; none → unknown), and being muted by that network takes points and lowers it. Measured on real accounts: the old rule rated 13 of 15 spam accounts "some", the new one none. Same rule as Quill.

Quick start

git clone https://github.com/rzazo24/nostrclaw && cd nostrclaw
npm install && npm run build

# Claude Code
claude mcp add nostrclaw -e NOSTRCLAW_RELAYS=wss://relay.hivescope.xyz -- node "$PWD/dist/index.js"

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "nostrclaw": {
  "command": "node", "args": ["/absolute/path/to/nostrclaw/dist/index.js"],
  "env": { "NOSTRCLAW_RELAYS": "wss://relay.hivescope.xyz" }
} } }

Then ask Claude things like “Audit my relay”, “What is the traffic of the last 24 hours made of?” or “Look at this key: npub1…”. The audit_relay prompt walks through a full review.

Related MCP server: Nostr Tools for AI Agents

Tools

recent_events, count_events, activity_report and author_report also take relays (2 to 8 configured relays) to ask all of them at once: answers are merged without duplicates, recent_events shows which relays hold each event, count_events gives one count per relay (not added up), and every result includes perRelay (what each returned, whether it was cut at the limit, its oldest/newest event). A relay that fails is reported and the rest still answer. With one relay the output is as before.

The two comparison tools need at least two relays in NOSTRCLAW_RELAYS (comma-separated).

recent_events, count_events and activity_report also accept a tags filter ({"e": [id]}, {"p": [pubkey]}, {"t": ["bitcoin"]}).

Publishing (optional, NIP-46)

Off by default. Enable it with NOSTRCLAW_ENABLE_SIGNING=1 and nine more tools appear:

Pairing through a bunker:// address (recommended for Clave)

A nostrconnect:// link works, but on iPhone Clave only answers signature requests while it is open on screen. Paired through a bunker:// address, Clave can be woken in the background by its push service. Copy the address from your signer, then run this in your own terminal (not through the assistant: the address carries a secret):

node dist/index.js connect-bunker --claude nostrclaw-sign   # asks for the address without showing it

It never prints the address or its secret, pairs with a new app key, and replaces the saved session only when the signer answers (the previous one is copied to signer.json.bak-before-bunker). Then restart Claude Code and call signer_connect: it resumes the saved session. The trust level you give it in the signer is your decision and does not change (keep it low: see the safety model).

How it stays under your control:

• Your key never leaves your signer. nostrclaw holds only an app key that identifies it to the signer, saved with mode 0600.

• A human decides, through a channel the model cannot write to. If your client supports it, publish_event asks you (MCP elicitation) showing the exact event, who signs it and where it goes; without an explicit yes nothing is signed. Your signer then asks for its own approval.

• Clave in the background: paired through a bunker:// address (see above), Clave answered with the app in the background even at low trust: the connection resumed on its own and a signature request arrived to be approved (measured 2026-10-09, running Claude Code from Termius on the same iPhone as Clave, the setup that failed with nostrconnect://: one reaction, signed in about 6 s, published to 6 relays). Paired through a nostrconnect:// link, with manual approval (low trust) Clave shows a blank notification and waits for you; tap it and approve, and for signing keep it open on screen. nostrclaw keeps asking for about two and a half minutes while you do.

• Use manual approval in the signer (Clave: low trust). If the signer approves by itself, anything that can read the app key saved on your machine — including an assistant with a shell — could ask it for signatures with no prompt; nostrclaw warns when it sees that.

• “Always allow” is detected. Without elicitation, the signer's approval is the lock — so it is verified: a signature that comes back faster than a person could decide (default 2 s) is discarded and never published, and further publishing is refused until you fix the signer and reconnect.

• Policy you own (~/.config/nostrclaw/policy.json, no tool can write it): allowed kinds (default notes 1 and reactions 7 only; add 5 to let you delete your own events), signatures per hour (default 5; counts signatures actually made), maximum length, relays, and blocked patterns (anything that looks like an nsec1…, bunker://, secret=…). An invalid file stops the server.

• The model cannot alter or replay anything: publish_event takes only a draft id; the signed event is checked against the draft and goes only to the relays, never back into the conversation.

• Audit log (~/.local/state/nostrclaw/audit.jsonl): every step with ids and hashes, never content or secrets.

Quick start with Clave on the iPhone:

claude mcp add nostrclaw -e NOSTRCLAW_ENABLE_SIGNING=1 -e NOSTRCLAW_RELAYS=wss://relay.hivescope.xyz -- node "$PWD/dist/index.js"

Then ask Claude to “connect my signer”, open the link it gives you in Clave and approve (do not choose “always allow”), and ask it to “draft a note saying …”. The connection link lists wss://relay.powr.build as well as your relay, because Clave only receives background requests through that one.

Recommended instead for Clave on iPhone: pair once with a bunker:// address (section above) and skip this link.

Your own bunker instead of Clave (optional)

connect-bunker accepts the bunker:// address of any NIP-46 signer, including one you run on your own server (the author uses hivescope-bunker: key encrypted on disk, unlocked by hand after each restart, one connection per app with its own list of kinds and an hourly limit). The pairing is the same: run connect-bunker in your own terminal and paste the address.

Two things change, and you should decide them knowingly:

• Your key lives (encrypted) on that server, not in your phone's keychain. Anyone with root on the machine while the bunker is unlocked can sign within the connection's limits.

• That signer approves by policy, not by a person, so its signatures come back in a fraction of a second. nostrclaw discards a signature that arrives faster than minHumanApprovalMs (default 2000), because that usually means "approve always" on a signer that was supposed to ask. With a bunker of your own that is expected, so set "minHumanApprovalMs": 0 in policy.json (a file only you can edit). What still stands: publish_event asks you before every signature, through a channel the model cannot write, and the bunker's own connection allows only the kinds and the rate you gave it.

Safety model

An assistant reading a public network is exposed to text written by strangers, so the design assumes everything from the network is hostile:

• Read-only by default. The analysis tools publish, sign, delete or change nothing and declare readOnlyHint. Writing exists only behind NOSTRCLAW_ENABLE_SIGNING=1 and the rules above.

• Untrusted text is fenced. Event content, profile fields and the relay's own description are returned only under an untrusted key, with a note telling the model to treat it as data and never follow instructions found in it. Signals and statistics never contain third-party text.

• Hidden characters are removed from everything third-party (zero-width, bidirectional overrides, control and Unicode “tag” characters) and long text is truncated.

• Relay allowlist. Tools only talk to the relays in NOSTRCLAW_RELAYS, so a prompt cannot make this process connect elsewhere. Local and private addresses are refused unless NOSTRCLAW_ALLOW_PRIVATE=1, HTTP redirects are not followed and responses are size-limited.

• Signatures are verified; events with a bad signature are dropped and counted.

• Bounded output: limits on events per call, sample sizes and timeouts.

Configuration

Troubleshooting: nostrclaw doctor

If something does not work, run the doctor. It is read-only (it never signs, publishes or writes) and it never prints secrets:

node dist/index.js doctor --claude nostrclaw-sign      # the settings Claude Code really launches, read from ~/.claude.json
node dist/index.js doctor --claude nostrclaw-sign --check-signer   # also resume the session and ping Clave (open it on screen first)
node dist/index.js doctor --json                        # machine-readable; exit code 1 when there is a problem

It checks the Node version, the configuration, each relay (allowed address, NIP-11, a real query, authentication or payment limits), policy.json, the saved signer session (permissions, damage, whether it uses relay.powr.build), the audit log, and — with --check-signer — that the signer answers. Every finding says what is wrong and how to fix it. Without --claude it reads NOSTRCLAW_* from the shell's environment.

Development

npm test                    # builds, then unit tests (safety, analysis, tools with a pretend network)
RELAY_BIN=/path/to/nostr-relay-khatru npm test   # …plus end-to-end tests against a real relay and over real stdio

The signing tests run a pretend NIP-46 signer (test/fake-signer.ts) through the real relay. Without RELAY_BIN the end-to-end tests are skipped (a sibling checkout of nostr-relay-khatru is picked up automatically). CI builds that relay and runs everything.

Roadmap

1. 0.1: read-only analysis.

2. 0.2: NIP-46 signing, opt-in — connect to a remote signer, draft events, publish only after explicit human confirmation. Design and threat model in docs/signing-design.md.

3. 0.3 – 0.9 (now): account_triage, event_engagement, trust_score (web of trust), compare_relays and event_locations (propagation between relays), review_interactions (bots), draft_reaction / draft_reply, a quick signer check before asking you, retry_publish, nostrclaw doctor, and analysis across several relays at once.

4. 0.10: deleting your own events (NIP-09), opt-in.

5. Ideas, not started: publishing the package on npm.

License

MIT