Bitcoin SV MCP Server

BSV MCP

BSV MCP 可将 AI 助手连接到 Bitcoin SV。你可以让它检查交易、显示余额、发送付款，或创建和交易 Ordinals（记录在区块链上的内容）。

文档 · 所有工具 · npm · 问题反馈

安装

安装 Bun 以运行服务，并安装 Node.js 以运行下方的 npx 命令，然后将其添加到你的客户端：

# Codex
codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Claude Code
claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Grok Build
grok plugin install b-open-io/bsv-mcp --trust

选择一条命令。对于 Cursor 或 Claude Desktop，请使用以下服务配置：

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"]
    }
  }
}

重启客户端，然后询问：“运行 bsv_status 并说明有哪些可用功能。” 本地 stdio 无需 Sigma 账户或 OAuth 登录。未指定传输方式时也默认使用本地 stdio。现有的自托管 HTTP 仍需通过 TRANSPORT=http 显式启用；已部署的托管端点保持不变。

对于 Codex 桌面插件，请在插件市场中添加 b-open-io/claude-plugins，并安装 BSV MCP。该插件会启动本地 npm 可执行文件，并需要 Node.js 和 Bun。Claude Code 和 Grok 插件捆绑了本地服务，需要 Bun。选择一种注册方式，以避免工具重复。

连接钱包

让助手运行 wallet_onboarding。在本地浏览器中创建、导入或解锁 Vault。充值前请先备份。仅在本地设置界面中输入密码，切勿在聊天中输入。重启服务后，请再次解锁。

若要使用现有的 BRC-100 钱包，请改为配置其签名 API：

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"],
      "env": {
        "BRC100_WALLET_URL": "http://127.0.0.1:3321",
        "BRC100_WALLET_ORIGINATOR": "bsv-mcp.local"
      }
    }
  }
}

钱包会保管密钥并控制权限请求。其签名 API 与钱包存储端点是分开的。有关网络设置、账户选择和项目角色，请参阅钱包设置。

该软件包还包含基于 Bun 的 bsv-mcp-local 启动器，可显式用于外部、旧版嵌入式和项目配置。源代码检出示例位于安装指南中。

MCP 协议兼容性

优先使用协议修订版 2026-07-28；在 stdio 和 HTTP 上会自动接受受支持的 2025 客户端。无需设置兼容性覆盖项。只有在要求使用现代客户端时，才设置 MCP_LEGACY_COMPATIBILITY=false。此设置也会传递给本地启动器。已通过旧版请求验证已安装的桌面客户端；现代客户端支持情况另行测试。

现代客户端支持钱包操作和请求级审批。审批续接会保留原始操作，并绑定到经过身份验证的用户、参数和过期时间。拒绝、取消或撤销会话都会停止操作；重放续接不会重复执行交易。不支持表单征询的客户端无法批准支出。外部钱包仍使用其自身的签名者权限流程。托管路由仅开放公开读取。

对于拆分式 SDK v2 客户端：

const client = new Client(
  { name: "my-app", version: "1" },
  { versionNegotiation: { mode: "auto" }, capabilities: { elicitation: { form: {} } } },
);

使用依赖审批的工具前，请先注册真实的人类审批处理程序。默认启用旧版协议兼容性；连接的客户端必须支持所请求工具所需的审批流程。

完整工具目录仍为默认设置，并根据能力生成：钱包模式、已启用模块、账户上下文和所选配置共同决定 tools/list 返回的内容。已纳入版本控制的清单是针对一个已配置服务的合成基线，并不代表默认工具数量固定。只有在需要使用范围受限的读取类别时，才设置 MCP_TOOL_CATALOG=compact；紧凑模式使用相同的底层处理程序。工具是否可用仍取决于钱包模式和已启用模块。其读取类别基线为 bsv_read、ordinals_read、wallet_read 和 utility，每类都具有范围受限的操作枚举；未知操作会被拒绝。符合条件的会话还会开放独立的可变更 wallet_setup 和 wallet_payments 类别。有关各类别的操作范围、端点约定、MCP Apps 兼容性和验证状态，请参阅 MCP 客户端协议支持指南。

社交

完整目录和紧凑目录中都包含两个用于社交操作的工具：

• bsocial_read：帖子、回复、搜索、点赞、好友、频道、消息、视频和原始操作历史。
• bsocial_publish：帖子／回复、转发、点赞／取消点赞、关注／取消关注、好友／解除好友记录、消息和视频记录。标签和附件使用单独且分别签名的输出。

{"action":{"type":"post","content":"Hello Bitcoin","tags":["bitcoin"]},"preview":true}

预览会返回未签名的输出，不会使用密钥或花费资金。移除 preview 后，即可通过所选身份钱包的现有权限发布。消息默认公开，除非其内容已提前加密；收件人上下文不会对消息加密。好友记录会公布通过既定密钥协商工作流生成的通信公钥。

有关示例以及如何从旧工具名称迁移，请参阅社交指南。PUBLIC_BMAP_URL 是索引器服务根路径（带有 /social 和 /q 路由），不是钱包或身份 API。原始关注／取消关注记录是事件历史，并不代表当前的关系状态。

本地钱包模式

外部模式连接到现有的 BRC-100 签名器。签名器保管私钥、钱包存储和权限决策；BSV MCP 仅接收 SDK 签名器接口。嵌入式模式使用加密的本地 Vault 钱包。钱包就绪屏幕会显示一个交互式云图，其中包含已连接会话的可用工具，这些工具根据其实时目录生成。

需要设置时，wallet_onboarding 会打开私密浏览器流程，以创建、导入或解锁钱包。所选账户的数据库和存储配置会继续使用。启动器的现有账户嵌入式模式仍会在运行时提供 BSV_MCP_PASSWORD。 项目模式会打开所有明确分配的角色：payments、identity-signing、one-sat 和 encryption。该模式要求成对的项目选择器，并且需要在运行时提供 BSV_MCP_PASSWORD；如果 Vault 模块未提供默认路径，请设置 VAULT_PATH。绑定会固定所选公钥，并支持直接密钥、BRC-42 子密钥和 BRC-157/Yours 个人资料叶节点。更改项目绑定或会话过期会撤销已捕获的句柄。派生密钥使用独立存储；选择账户的支付根密钥会保留其现有数据库和存款前缀。

BRC-100 工具接受 walletRole（payments、identity、ordinals 或 encryption）。方法默认值会选择对应角色，签名/中止操作的后续调用会保留其来源钱包和经过身份验证的用户。未分配的角色会报错，而不会借用其他密钥。BAP 工具使用身份钱包进行发布、轮换、证明和个人资料操作，而不会导出 xprv。该钱包也会为这些交易提供资金并保留 BAP 记录。已签名的 BSocial 帖子和 SIGMA 铭文使用配置的身份。

外部注册可以使用相同的项目根目录/ID 配对来派生隔离的权限来源，且无需 Vault 密码。可选的 BRC100_WALLET_PUBLIC_KEY 用于固定签名器身份。BRC100_WALLET_ROLES 是一个 JSON 对象，用于选择独立的角色端点和公钥固定值；请参阅外部签名器配置。源代码启动器接受 external --project-root /absolute/project --project-id project.example。默认情况下会禁用广播；在其运行环境中设置 DISABLE_BROADCASTING=false，即可在签名器批准后启用交易工具。

每种模式都有自己的进程环境；需要在它们之间切换时，应将每种模式注册为单独的服务。仅使用项目所需的注册项。

嵌入式钱包可以列出待处理的 PeerPay 付款，并使用 wallet_peerPayments 接收选定的付款。接收操作需要消息 ID，并且只会在钱包接受消息后确认该消息。这些操作无需支付 MessageBox 服务费。外部签名器和 Droplit 不提供此工具。项目会话必须分配支付角色。

查找技能

使用 utils_find_skills 和简短的关键词查询，在 bOpen 目录中查找技能。它最多返回五条描述以及指向带版本号的 SKILL.md 文件的链接。它不会下载技能内容或安装插件。在紧凑模式下，从 utility 工具中选择 utils_find_skills。

静态教程提示词和 BRC/BitCom 资源目录已停用。请使用技能查找器查找这些参考资料。变更日志、JungleBus 文档和仪表盘应用资源仍可使用。

准备好你的钱包和基础设施

使用 BRC100_WALLET_URL 连接兼容的现有钱包，或使用本地 Vault 浏览器设置（wallet_onboarding）。BSV_MCP_PASSWORD 仅供无头 Agent 使用：在该会话的进程环境中设置，切勿在 MCP 客户端配置中设置。PRIVATE_KEY_WIF 和 IDENTITY_KEY_WIF 是迁移来源，不是用于实时签名的密钥；请将它们导入 Vault，并删除明文副本。启动时绝不会创建密钥。所需的钱包 API 和配置请参阅钱包设置指南。

默认的 1Sat API 后端为 https://api.1sat.app。新的主网嵌入式账户默认使用 https://wallet.1sat.app 存储钱包；除非另行配置，测试网账户不会选择远程存储提供方。使用 ONESAT_API_URL 覆盖 API 服务地址，使用 REMOTE_STORAGE_URL 覆盖钱包存储地址；这是两项独立设置。可用工具取决于钱包模式和启用的模块。

• 钱包设置
• 后端配置
• 工具和工作流
• 付费服务请求
• 赞助和 Agent 委派
• 故障排除和开发

开发

bun install
bun run dev          # Website
bun run build:all    # MCP server and dashboard
# Supply BRC100_WALLET_URL in the host environment before this launch.
bun --no-env-file scripts/local-mcp-launcher.ts external # Source-checkout local launch
bun test

本软件为实验性软件；API 可能会变更。请备份钱包。如果交易请求超时，请先确认交易是否成功，再重新发送。采用 MIT 许可证。

准备发布包

package.json 中的 "files" 决定 tarball 内容。prepack 会运行 bun run build:all。 使用 bun publish 发布。编译时库属于 devDependencies； 使用者获得的是打包后的 dist/ 文件，而不是第二份源代码树。