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. By default it is read-only. Optionally (off until you enable it) Claude can also draft and publish notes and reactions 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.

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 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 five more tools appear:

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.

• 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), publications per hour (default 5), 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.

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

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 (now): 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. Later: more analysis (multi-relay comparison, follow-graph / web-of-trust signals).

License

MIT