io.github.llmops-pro/nostr-ops-mcp

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)

Tool	Purpose
nostr_decode	Parse NIP-19 strings (npub / nsec / note / nevent / naddr / nprofile). nsec decoding gated behind NOSTR_ALLOW_NSEC_DECODE=true.
nostr_encode	Build NIP-19 strings from raw fields. nsec encoding deliberately not supported.

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

Tool	Purpose
nostr_get_pubkey	Returns the signer's pubkey + npub. Errors clearly if no signer configured.
nostr_list_relays	Configured relay pool + each relay's connection status.
nostr_query_events	The workhorse. NIP-01 filters: kinds, authors, e_tag / p_tag / d_tag / t_tag tag filters (mapped to NIP-01 #e/#p/#d/#t internally — renamed in v0.2.0 for hosted-API schema compatibility), since / until / limit.
nostr_get_profile	Fetch + parse kind:0 metadata for a pubkey or npub. Returns the parsed JSON content (name, about, picture, nip05, lud16, …).
nostr_verify_nip05	Resolve name@domain → pubkey via /.well-known/nostr.json. Optional expected_pubkey for verification mode.

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

Tool	Purpose
nostr_publish_event	The primitive write tool. Pass kind / content / tags.
nostr_publish_text_note	Convenience for kind:1. Reply/mention/hashtag shortcuts auto-assemble into NIP-10 tags.
nostr_publish_metadata	Kind:0 profile. Always demands two-step confirmation regardless of NOSTR_REQUIRE_CONFIRM — overwriting your profile is hard to reason about.
nostr_publish_addressable_event	Kinds 30000–39999 (replaceable). Sets the d tag automatically. The bridge marketplace-mcp uses for NIP-15.
nostr_delete_event	NIP-09 kind:5 soft delete. Best-effort — relays may ignore.
nostr_confirm_publish	Execute a token-gated publish. Single-use; safety pipeline re-runs.

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

Tool	Purpose
nostr_send_dm	NIP-04 (kind:4) DM with NIP-44 encryption by default; NIP-04 supported for legacy compat. Gated by NOSTR_DM_ALLOWLIST.
nostr_list_dms	Fetch + decrypt the thread with a counterparty. Auto-detects NIP-44 vs NIP-04 per event.
nostr_decrypt_dm	Decrypt a single ciphertext (when you already have the event from elsewhere).

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

Var	Purpose
NOSTR_RELAYS	Comma-separated wss:// relays. Server refuses to start if empty.
NOSTR_ALLOWED_KINDS	Comma-separated event-kind numbers the server may sign. Required when a signer is configured. Example: 1,30017,30018 for text-note + NIP-15 marketplace. Default omits kind:0 (profile) and kind:5 (delete) — both easy to misuse.

Signer — provide AT MOST one

Var	Purpose
NOSTR_NIP46_URI	bunker://<pubkey>?relay=...&secret=... from Amber / nsec.app / Alby Account / any NIP-46 bunker. Recommended.
NOSTR_PRIVATE_KEY	Raw nsec1.... Dev/legacy only. Server warns at startup.

Optional safety knobs

Var	Default	Purpose
NOSTR_READ_ONLY	false	Force read-only — disables all write tools.
NOSTR_DM_TOOLS_ENABLED	false	Opt-in for send_dm / list_dms / decrypt_dm.
NOSTR_DM_ALLOWLIST	unset	Hex pubkeys allowed as DM recipients. Empty = NOSTR_DM_TOOLS_ENABLED alone gates.
NOSTR_REQUIRE_CONFIRM	false	Two-step confirm: write tools return a token, nostr_confirm_publish executes.
NOSTR_MAX_EVENTS_PER_MINUTE	10	Rolling 60s rate limit on writes.
NOSTR_MAX_DMS_PER_MINUTE	5	Same but for DMs.
NOSTR_ALLOW_NSEC_DECODE	false	Allow nostr_decode to return raw private key material. Don't enable unless you really need it.
NOSTR_LOG_PATH	./nostr-mcp.log	Server log path.
NOSTR_AUDIT_PATH	./nostr-mcp-audit.log	Structured audit log (one JSON line per tool call).

---

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.

• NOSTR: npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — follow, DM, zap.
• Lightning Address: sovereigncitizens@getalby.com — for support zaps and "this was useful" tips.
• Bug reports / feature requests: open a GitHub issue (link forthcoming).
• Security issues: please disclose privately via NOSTR DM before opening a public issue.