nostr-ops-mcp

nostr-ops-mcp

为你的 LLM Agent 提供 NOSTR 身份。 MCP 服务将 NOSTR 协议原语（签名、发布、查询、NIP-19 编码/解码、NIP-05 查询、加密私信）作为 Agent 可调用的工具。将它添加到 Claude Desktop、Claude Code、Cursor 或任何支持 MCP 的客户端中。为 Agent 提供 NIP-46 bunker 密钥（而非原始 nsec）。设置 kind 允许列表。在你掌控的限制范围内，让它代表你发帖。

v0.1 — 完整的读取、写入和私信功能。 16 个工具由纵深防御安全机制保护：kind 允许列表（默认拒绝）、收件人允许列表、速率限制、可选的两步确认、结构化审计日志。支持 nsec（开发环境）和 NIP-46 bunker（生产环境）。

---

你可以用它做什么

• 使用你的 npub 发布 kind:1 笔记的机器人 — 每日摘要、定时发帖、对收到的事件做出程序化回应。
• NOSTR 销售 Agent — 与 marketplace-mcp 搭配，以同一身份发布 NIP-15 摊位和产品。
• 个人资料管理 — 使用 nostr_publish_metadata 发布 kind:0（始终需要确认——如果没有更早的中继数据，覆盖个人资料将无法撤销）。
• 私信驱动的工作流 — 监控收到的私信（使用 nostr_list_dms）、解密订单并通过 nostr_send_dm 回复的店铺 Agent。默认关闭，由 NOSTR_DM_TOOLS_ENABLED 控制。
• 跨服务身份 — 在 nostr-ops-mcp 和 marketplace-mcp 之间共享同一个 NIP-46 bunker URI。一个密钥、一个身份、两组专用工具。

安全机制是它能在生产环境中使用的关键：拥有代表你发布权限的密钥的 Agent，如果不加约束，几秒钟内就可能毁掉你的声誉。该服务会限制它能签署的 kind 和速率，可选要求第二步确认，并将每次调用写入结构化审计日志。

---

16 个工具

只读 — 本地（无需网络，也不需要签名器）

工具	用途
nostr_decode	解析 NIP-19 字符串（npub / nsec / note / nevent / naddr / nprofile）。解码 nsec 受 NOSTR_ALLOW_NSEC_DECODE=true 控制。
nostr_encode	根据原始字段构建 NIP-19 字符串。刻意不支持编码 nsec。

只读 — 网络（查询/个人资料/NIP-05 无需签名器）

工具	用途
nostr_get_pubkey	返回签名器的公钥和 npub。未配置签名器时会明确报错。
nostr_list_relays	已配置的中继池以及各中继的连接状态。
nostr_query_events	核心工具。NIP-01 筛选条件：kinds、authors、e_tag / p_tag / d_tag / t_tag 标签筛选（内部映射至 NIP-01 #e / #p / #d / #t——为兼容托管 API 架构，于 v0.2.0 重命名）、since / until / limit。
nostr_get_profile	获取并解析公钥或 npub 对应的 kind:0 元数据。返回解析后的 JSON 内容（name、about、picture、nip05、lud16 等）。
nostr_verify_nip05	通过 /.well-known/nostr.json 将 name@domain 解析为公钥。可选使用 expected_pubkey 进入验证模式。

写入（需要签名器；受 KindAllowlist、RateLimiter 和可选确认机制控制）

工具	用途
nostr_publish_event	基础写入工具。传入 kind / content / tags。
nostr_publish_text_note	便捷发布 kind:1。回复/提及/话题标签快捷方式会自动组装为 NIP-10 标签。
nostr_publish_metadata	kind:0 个人资料。无论 NOSTR_REQUIRE_CONFIRM 如何设置，始终需要两步确认——覆盖个人资料的后果难以预料。
nostr_publish_addressable_event	Kinds 30000–39999（可替换）。自动设置 d 标签。桥接服务 marketplace-mcp 用它处理 NIP-15。
nostr_delete_event	NIP-09 kind:5 软删除。尽力而为——中继可能会忽略。
nostr_confirm_publish	执行由令牌授权的发布。仅可使用一次；安全流程会重新运行。

私信（风险最高；默认关闭，通过 NOSTR_DM_TOOLS_ENABLED=true 启用）

工具	用途
nostr_send_dm	默认使用 NIP-44 加密的 NIP-04（kind:4）私信；支持 NIP-04，以兼容旧版。受 NOSTR_DM_ALLOWLIST 限制。
nostr_list_dms	获取并解密与通信对象的对话串。会按事件自动检测使用的是 NIP-44 还是 NIP-04。
nostr_decrypt_dm	解密单条密文（当你已从其他来源获取该事件时）。

目前尚不支持 NIP-17 密封／礼物包装私信——已推迟到未来的 v0.2 版本（传闻事件和礼物包装会带来不小的复杂性）。

---

要求

• Node 20+
• 一个 NOSTR 签名器——**强烈建议：**使用来自 Amber（Android）、nsec.app（Web）或任何其他 NIP-46 实现的 NIP-46 bunker URI。**旧版方式：**在 .env 中使用原始 nsec。检测到磁盘上存在 nsec 时，服务会在启动时向 stderr 输出警告。

安装

# 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

配置

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)

服务会自动从此二进制文件所在目录（dist/ 旁）加载 .env——有意不从 cwd 加载，以避免多个 MCP 服务在同一个 Claude Code 会话中运行时发生环境变量冲突。

必填

变量	用途
NOSTR_RELAYS	以逗号分隔的 wss:// 中继。为空时服务会拒绝启动。
NOSTR_ALLOWED_KINDS	以逗号分隔的事件 kind 数字，表示服务允许签名的事件类型。配置签名器时必填。例如，文本笔记 + NIP-15 市场可设为 1,30017,30018。默认不包含 kind:0（个人资料）和 kind:5（删除）——这两种都很容易被误用。

签名器 — 最多提供一个

变量	用途
NOSTR_NIP46_URI	来自 Amber / nsec.app / Alby Account / 任何 NIP-46 bunker 的 bunker://<pubkey>?relay=...&secret=...。推荐。
NOSTR_PRIVATE_KEY	原始 nsec1...。仅用于开发／旧版方式。服务会在启动时发出警告。

可选安全设置

变量	默认值	用途
NOSTR_READ_ONLY	false	强制只读——禁用所有写入工具。
NOSTR_DM_TOOLS_ENABLED	false	选择启用 send_dm / list_dms / decrypt_dm。
NOSTR_DM_ALLOWLIST	未设置	允许作为私信接收方的十六进制公钥。为空时，仅由 NOSTR_DM_TOOLS_ENABLED 控制启用。
NOSTR_REQUIRE_CONFIRM	false	两步确认：写入工具返回令牌，再由 nostr_confirm_publish 执行。
NOSTR_MAX_EVENTS_PER_MINUTE	10	写入操作的滚动 60s 速率限制。
NOSTR_MAX_DMS_PER_MINUTE	5	同上，但针对私信。
NOSTR_ALLOW_NSEC_DECODE	false	允许 nostr_decode 返回原始私钥材料。除非确有需要，否则不要启用。
NOSTR_LOG_PATH	./nostr-mcp.log	服务日志路径。
NOSTR_AUDIT_PATH	./nostr-mcp-audit.log	结构化审计日志（每次工具调用写入一行 JSON）。

---

接入 MCP 客户端

Claude Code（项目级）

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

Claude Desktop / Cursor / 其他客户端

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

由于服务会加载自己的 .env，请将客户端配置中的 env 块留空——不要将机密信息放入任何已提交的文件中。

---

安全模型

每个写入工具都会按以下顺序执行流程：

1. NOSTR_READ_ONLY 门控 — 直接拒绝。
2. 签名者是否存在 — 如果未配置 nsec 或 NIP-46 URI，则拒绝。
3. KindAllowlist — 如果事件类型不在 NOSTR_ALLOWED_KINDS 中，则拒绝。
4. RateLimiter — 如果滚动 60s 的 events 桶已满，则拒绝。
5. 确认门控 — 如果 NOSTR_REQUIRE_CONFIRM=true（或该工具始终要求确认，例如 publish_metadata），则返回一个 16 字节的十六进制令牌，而不是签名。
6. 签名 + 发布 — 通过 NDK 执行；签名者握手会在首次使用时延迟完成（这与 NIP-46 有关，因为 bunker 握手是异步的）。
7. 审计日志 — 为每次尝试追加一行 JSON（成功 / 阻止 / 错误）。

DM 工具还会额外执行三项检查：NOSTR_DM_TOOLS_ENABLED、DmAllowlist（按收件人设置）以及独立的 dms 速率桶。

安全底线取决于你的签名者。 如果使用 NIP-46，bunker 可以拒绝任何签名请求，这是最强的安全边界。本服务的检查则是额外的多重保障。

验证调用是否确实成功

tail -n 5 nostr-mcp-audit.log

发布成功时：{"ts":"...","tool":"nostr_publish_text_note","outcome":"ok","result":{"event_id":"...","relays_accepted":[...]}}。阻止 / 错误日志的结构也相同。审计日志的设计是只追加 — 请将日志轮换纳入日常运维。

---

测试

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

若要针对在线中继进行端到端测试，请配置一个临时 nsec 和几个公共中继（damus.io、nos.lol），然后运行一个小循环：nostr_publish_text_note → nostr_query_events，确认笔记完成往返。nostr_send_dm → nostr_list_dms 循环可验证 DM 流程（你可以给自己发 DM 来进行闭环检查）。

---

配套服务

• nwc-mcp — 通过 NWC 使用 Lightning 钱包。将它们配对，即可构建会花费 sats 的 NOSTR Agent。
• marketplace-mcp — NIP-15 市场发布（兼容 Shopstr）。使用与本服务相同的签名者配置。

---

许可证

MIT — 参见 LICENSE。

联系方式 / 问题反馈

由 LLMOps.Pro 构建。

• NOSTR： npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — 关注、发 DM、打赏。
• Lightning Address： [email protected] — 可用于支持打赏和“这很有用”的小费。
• 错误报告 / 功能请求： 请提交 GitHub issue（链接即将提供）。
• 安全问题： 请先通过 NOSTR DM 私下披露，再提交公开 issue。