nostr-ops-mcp

A NOSTR identity for your LLM agent. MCP server that exposes NOSTR protocol primitives — sign, publish, query, NIP-19 encode/decode, NIP-05 lookup, encrypted DMs — as tools your agent can call. Drop it into Claude Desktop, Claude Code, Cursor, or any MCP-speaking client. Hand the agent a NIP-46 bunker key (not a raw nsec). Set a kind allowlist. Let it post on your behalf within rails you control.

v0.1 — full read + write + DM surface. 16 tools wrapped in a defense-in-depth safety stack: kind allowlist (deny-by-default), recipient allowlist, rate limits, optional two-step confirmation, structured audit log. Supports both nsec (dev) and NIP-46 bunker (production).

What you can do with this

• A bot that publishes kind:1 notes from your npub — daily summaries, scheduled posts, programmatic reactions to incoming events.
• A NOSTR sales agent — pair with marketplace-mcp to publish NIP-15 stalls + products as the same identity.
• Profile management — nostr_publish_metadata for kind:0 (always demands confirmation — overwriting your profile is irreversible without older relay data).
• DM-driven workflows — a storefront agent that watches incoming DMs (with nostr_list_dms), decrypts orders, and replies via nostr_send_dm. Default-off behind NOSTR_DM_TOOLS_ENABLED.
• Cross-server identity — share the same NIP-46 bunker URI across nostr-ops-mcp and marketplace-mcp. One key, one identity, two specialized tool surfaces.

The safety stack is the load-bearing reason this is usable in production: an agent with the keys to publish as you can ruin your reputation in seconds if unconstrained. The server enforces what kinds it'll sign, what rate, optional second-step confirmation, and writes every call to a structured audit log.

The sixteen tools

Read-only — local (no network, no signer needed)

Read-only — network (no signer needed for query/profile/nip05)

Write (require signer; gated by KindAllowlist + RateLimiter + optional confirm)

DMs (highest-risk; default-off via NOSTR_DM_TOOLS_ENABLED=true)

NIP-17 sealed/gift-wrapped DMs are not yet supported — deferred to a future v0.2 (rumor events + gift-wrapping add nontrivial complexity).

Requirements

• Node 20+
• A NOSTR signer — strongly preferred: a NIP-46 bunker URI from Amber (Android), nsec.app (web), or any other NIP-46 implementation. Legacy path: a raw nsec in .env. The server logs a stderr warning at startup when nsec-on-disk is detected.

Install

# From npm (once published)
npx -y nostr-ops-mcp

# From source
git clone <repo>
cd nostr-ops-mcp
corepack enable pnpm
pnpm install
pnpm build

Configure

cp .env.example .env
# edit .env: set NOSTR_NIP46_URI (recommended) OR NOSTR_PRIVATE_KEY
#           set NOSTR_RELAYS (comma-separated wss://)
#           set NOSTR_ALLOWED_KINDS (required when a signer is configured)

The server auto-loads .env from this binary's own directory (next to dist/) — deliberately NOT from cwd, to avoid env-var collision when multiple MCP servers run in the same Claude Code session.

Required

Signer — provide AT MOST one

Optional safety knobs

Wire into an MCP client

Claude Code (project-scoped)

claude mcp add nostr-ops -s project node "$(pwd)/dist/index.js"

Claude Desktop / Cursor / other clients

{
  "mcpServers": {
    "nostr-ops": {
      "command": "npx",
      "args": ["-y", "nostr-ops-mcp"],
      "env": {}
    }
  }
}

Because the server loads its own .env, leave the env block empty in the client config — keep secrets out of any committed file.

Safety model

Every write tool runs the pipeline in this order:

1. NOSTR_READ_ONLY gate — refuse outright.
2. Signer presence — refuse if neither nsec nor NIP-46 URI is configured.
3. KindAllowlist — refuse if the event kind isn't in NOSTR_ALLOWED_KINDS.
4. RateLimiter — refuse if the rolling 60s events bucket is full.
5. Confirm gate — if NOSTR_REQUIRE_CONFIRM=true (or the tool always-confirms, like publish_metadata), return a 16-byte hex token instead of signing.
6. Sign + publish — via NDK; the signer handshake completes lazily on first use (relevant for NIP-46 where the bunker handshake is async).
7. Audit log — append-only JSON line for every attempt (ok / blocked / error).

DM tools add three more checks on top: NOSTR_DM_TOOLS_ENABLED, DmAllowlist (per-recipient), and a separate dms rate bucket.

The floor is your signer. If using NIP-46, the bunker can refuse any sign request — that's the strongest safety boundary. This server's checks are belt-and-suspenders on top.

Verifying calls actually went through

tail -n 5 nostr-mcp-audit.log

Successful publish: {"ts":"...","tool":"nostr_publish_text_note","outcome":"ok","result":{"event_id":"...","relays_accepted":[...]}}. Blocked / error lines are equally structured. The audit log is append-only by intent — rotate it as part of your operational hygiene.

Testing

pnpm typecheck   # tsc --noEmit
pnpm test        # 13 vitest cases (KindAllowlist, RateLimiter, nip19 roundtrip)
pnpm build       # dist/index.js (~58 KB ESM bundle)

For end-to-end testing against live relays, configure a throwaway nsec + a couple of public relays (damus.io, nos.lol) and run a small loop: nostr_publish_text_note → nostr_query_events to confirm the note round-tripped. The nostr_send_dm → nostr_list_dms loop validates the DM path (you can DM yourself for a closed-loop check).

Companion servers

• nwc-mcp — Lightning wallet over NWC. Pair these to build sats-spending NOSTR agents.
• marketplace-mcp — NIP-15 marketplace publish (Shopstr-compatible). Uses the same signer setup as this server.

License

MIT — see LICENSE.

Contact / Issues

Built by LLMOps.Pro.