bolthub

@bolthub/mcp

bolthub MCP 服务。在 MCP 客户端配置中只需添加一个入口；它背后有三类工具来源，共用一个钱包和一份 Lightning 预算：

• bolthub marketplace — 搜索、查看并调用所有已上架的 API（search_apis、get_api_details、preview_cost、call_api、buy_credit、mint_scoped_token、revoke_token，以及 Node Launcher 工具）。
• 将你自己的 API 作为上架项目 — 将 OpenAPI/Postman 规范转换为需付费的上架草稿，根据卖家标准审核，准备就绪后正式发布，并追踪收益情况（list_api、analyze_listing、publish_listing、get_earnings、usage_summary）。这些操作会使用你的账户，因此需要令牌：说“连接我的 bolthub 账户”（connect_account 会启动一键浏览器配对；聊天中不会接触任何机密信息），或自行设置 BOLTHUB_ACCOUNT_TOKEN。购买无需账户。草稿在你明确发布前会保持不可见。
• 特定 L402 网关 — 网关的 OpenAPI 端点会成为名称直接对应的工具。
• 你的其他 MCP 服务 — 本地或远程服务均可透明代理：免费工具直接通过；如果某个工具返回 L402 付款质询，系统会从你的预算中支付，然后重试。

取代 @bolthub/mcp-registry 和 @bolthub/mcp-bridge（两者均已弃用——迁移方法见下文）。

源码：signaltech-org/bolthub-sdk · 文档：docs.bolthub.ai

快速开始

将以下内容添加到你的 MCP 客户端配置中（Cursor、Claude Desktop、OpenClaw 等）：

{
  "mcpServers": {
    "bolthub": {
      "command": "npx",
      "args": ["-y", "@bolthub/mcp"],
      "env": { "NWC_URI": "<your-nwc-connection-string>" }
    }
  }
}

如果没有配置文件，系统会以市场模式运行：你的 Agent 可以通过元工具使用 bolthub 上的所有 API。新上架的项目会自动出现，无需更改配置。

完整设置：一个配置文件

~/.bolthub/mcp.json — mcpServers 代码块的格式与你的 MCP 客户端当前使用的格式完全相同，因此可以直接粘贴你现有的条目：

{
  "marketplace": true,
  "gateways": ["https://btc-intel.gw.bolthub.ai"],
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"]
    },
    "remote-tools": {
      "url": "https://tools.example.com/mcp",
      "headers": { "Authorization": "Bearer …" }
    }
  },
  "budget":     { "sat": 10000 },   // lifetime ceiling for this run, ALL sources combined
  "maxPerCall": { "sat": 500 },     // per-call ceiling
  "namespace":  "prefix",           // "prefix" (default) or "flat"
  "telemetry":  false               // reserved; v1 sends nothing anywhere
}

然后让客户端使用该文件：

{
  "mcpServers": {
    "bolthub": {
      "command": "npx",
      "args": ["-y", "@bolthub/mcp", "--config", "~/.bolthub/mcp.json"],
      "env": { "LND_REST_HOST": "…", "LND_MACAROON": "…" }
    }
  }
}

Agent 能看到什么

• 市场元工具，不带前缀：search_apis、get_api_details、preview_cost、call_api、buy_credit、mint_scoped_token、revoke_token、deploy_node、node_status、list_api、analyze_listing、publish_listing、get_earnings、usage_summary、connect_account、connect_status、create_workspace、connect_wallet、get_onboarding_state，以及用于实时 SSE 数据流的 open_stream / read_stream / close_stream。
• 配置钱包后可使用 wallet_status：查看 SPENDING 钱包（余额、权限、连接状态）——这是付款方对应的 node_status，也是付款失败时首先应运行的工具。
• 网关端点，前缀为网关 slug：btc-intel__get_v1_history_candles，……
• 下游 MCP 工具，前缀为其配置键：filesystem__read_file，……

两个服务可能都会提供名为 search 的工具——添加前缀即可区分。namespace: "flat" 会改为直接传递不带前缀的名称，并且遇到任何名称冲突时都会在启动阶段失败（不会静默隐藏任何工具）。

钱包（可选）

在服务的 env 中设置以下其中一项：

LND_REST_HOST + LND_MACAROON         (recommended, fastest <200ms)
NWC_URI                              (easiest setup, slower 1-3s)
LNBITS_URL + LNBITS_ADMIN_KEY        (alternative, <300ms)
PHOENIXD_URL + PHOENIXD_PASSWORD     (alternative, <200ms)

未设置钱包并非错误：免费工具和市场搜索仍可正常使用；付费调用会返回付款质询，并附带设置提示。

一份预算，严格保障

budget.sat 会限制服务整个生命周期内的总支出，涵盖网关调用、call_api 和付费下游 MCP 工具。预留额度会同步进行，因此不同来源的并发调用不会合计超支。budget.sat: 0 是有效值，表示“仅限免费工具”。Agent 永远无法提高上限；被拒绝的请求会返回清晰的“Payment refused”结果。

每笔付款都会将一行记录写入 stderr（作为你的本地审计记录）。telemetry 标志目前仅作保留：v1 无论开关状态如何都不会向任何地方发送数据；如果未来版本添加可选的数据接收功能，也只会传送 { scheme, asset, amount }，不会包含工具参数或资源身份信息。

从 @bolthub/mcp-registry / @bolthub/mcp-bridge 迁移

迁移前	迁移后
npx @bolthub/mcp-registry	npx @bolthub/mcp（零配置 = 行为相同）
npx @bolthub/mcp-registry --api-url <url>	npx @bolthub/mcp --api-url <url>
npx @bolthub/mcp-bridge --gateway <url>	npx @bolthub/mcp --gateway <url>
--budget / BUDGET_SATS	保持不变（现在所有来源共用一个池）
网关工具 btc-intel_get_v1_x	btc-intel__get_v1_x（双下划线命名空间）

请从客户端配置中移除旧条目，不要将它们与此配置并列添加——mcpServers 中嵌套的 bolthub 可执行文件会使用自己的钱包环境变量进行支付，无法计入共享预算（如果服务启动时发现这种情况，会发出警告）。

说明与限制（v1）

• 仅代理 MCP 工具——暂不支持资源、提示词或采样透传。
• 下游工具列表会在启动时快照；热添加或移除需要重启。
• 无法启动的下游服务会被跳过，并在 stderr 中发出警告；其余服务会继续提供服务。
• 所有日志都写入 stderr，从不写入 stdout（stdout 是 MCP 通道）。

许可证

MIT