nostr-mcp

A Model Context Protocol server for Nostr. Agents can read verified public data and act on Nostr: post notes and replies, react, repost, publish articles, manage drafts, send encrypted direct messages, upload media, and send Lightning zaps. Private keys stay out of the conversation because signing happens inside the server process.

Reads report relay provenance. Invalid signatures are discarded, duplicate events are merged, and partial relay failures show up in results instead of being hidden.

Quick start

# Register with Codex (or point any MCP host at the stdio command below)
npx -y @diegoaly_/nostr-mcp@latest install

# Create an encrypted identity (NIP-49 key file, passphrase prompted)
npx -y @diegoaly_/nostr-mcp@latest key generate

// Any MCP host. Signing activates when NOSTR_KEY_PASSPHRASE is present.
{
  "mcpServers": {
    "nostr": {
      "command": "npx",
      "args": ["-y", "@diegoaly_/nostr-mcp@latest"],
      "env": { "NOSTR_KEY_PASSPHRASE": "{your-passphrase}" }
    }
  }
}

With no identity configured the server runs read-only, and every write tool explains how to enable itself when called. If you would rather not hold keys locally at all, use a NIP-46 bunker: set NOSTR_BUNKER_URI=bunker://... from Amber on Android, and the key never touches this machine.

What it can do

Read & discover. Resolve any identifier (npub, note, nevent, naddr, NIP-05 handles), fetch profiles and events with relay provenance, reconstruct full threads, run full-text search over NIP-50 relays, look up NIP-65 relay lists, inspect NIP-11 relay documents.

Publish. Notes with automatic reply threading, reactions, reposts, deletes that check ownership first, profile editing that preserves unknown fields, and long-form markdown articles where republishing a slug edits the article.

Drafts, DMs, media, money. Encrypted local drafts. Sealed-sender private messages over NIP-17. Blossom media uploads that return ready-made imeta tags. Lightning zaps through Nostr Wallet Connect, capped by a server-side spend limit.

The complete tool reference lives in docs/tools.md, and the protocol coverage matrix in docs/nips.md.

Identity options

Zaps additionally need a wallet URI (NOSTR_WALLET_NWC, from Alby/Primal/Coinos). Per-zap spending is capped by NOSTR_MAX_ZAP_MSAT regardless of what an agent tries.

Full details in docs/configuration.md.

Documentation

Requirements

• Node.js 20.19 or newer

• An MCP host that supports stdio servers

Development

npm run check

Type checking, the offline test suite, build, a real-stdio smoke test, and npm package validation. See docs/development.md.

Security model

• Signing happens inside the server process; keys never appear in tool inputs, outputs, or logs

• NIP-49 encrypted keys at rest; NIP-46 bunker mode keeps keys off the machine entirely

• Server-enforced zap spend cap; destructive tools are annotated and gated behind explicit configuration

• Signature verification before events reach the agent; strict relay URL validation against SSRF

• Bounded relay counts, result sizes, and timeouts; per-relay errors reported, never swallowed

License

MIT