比特币与闪电网络支付 MCP 服务器

Blink MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Blink Bitcoin and Lightning Network API.

Features

• Lightning Network: Create and pay invoices, send to Lightning addresses
• On-Chain Bitcoin: Generate addresses, send transactions, estimate fees
• Stablesats (USD): Full support for USD-denominated wallets
• Intraledger Transfers: Free instant transfers between Blink users
• Webhooks: Register callbacks for payment notifications
• Real-time Subscriptions: Monitor invoice status and account updates
• Price Data: Get real-time and historical Bitcoin prices
• L402 Consumer: Discover, pay for, and cache tokens for L402-gated APIs
• L402 Producer: Create Lightning paywalls and verify payment tokens
• L402 Discovery: Search l402.directory and 402index.io for paid APIs

Prerequisites

• Node.js 24+
• A Blink wallet account (dashboard.blink.sv)
• A Blink API key

Installation

From Source

git clone https://github.com/yourusername/blink-mcp.git
cd blink-mcp
npm install
npm run build

Getting an API Key

1. Log in to your Blink wallet at dashboard.blink.sv
2. Go to Settings > API Keys
3. Click Create API Key
4. Select the permissions you need:
   • Read: View balances, transactions, and account info
   • Receive: Create invoices and addresses to receive payments
   • Write: Send payments and modify account settings
5. Copy the generated API key

Configuration

Set the following environment variables:

# Required: Your Blink API key
export BLINK_API_KEY=blink_xxxxxxxxxxxxx

# Optional: Network to use (default: mainnet)
export BLINK_NETWORK=mainnet  # or 'staging' for testnet

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on Linux/Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "blink": {
      "command": "node",
      "args": ["/path/to/blink-mcp/dist/index.js"],
      "env": {
        "BLINK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or if installed globally via npm:

{
  "mcpServers": {
    "blink": {
      "command": "blink-mcp",
      "env": {
        "BLINK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usage with Other MCP Clients

The server uses stdio transport. Run it with:

BLINK_API_KEY=your_key node dist/index.js

Available Tools

Wallet & Account (17 tools)

Lightning Network (12 tools)

On-Chain Bitcoin (7 tools)

Intraledger (Blink-to-Blink) (3 tools)

Webhooks & Subscriptions (9 tools)

L402 Protocol (6 tools)

Example Conversations

Check Balance

User: What's my Bitcoin balance?
Assistant: [Uses get_wallets tool]
Your BTC wallet has 50,000 sats and your USD wallet has $12.50.

Create Invoice

User: Create an invoice for 10,000 sats
Assistant: [Uses create_invoice tool]
Here's your Lightning invoice for 10,000 sats:
lnbc100u1p...

Send Payment

User: Send 1000 sats to user@blink.sv
Assistant: [Uses pay_lightning_address tool]
Payment of 1,000 sats sent successfully to user@blink.sv!

Monitor Invoice

User: Let me know when invoice lnbc... is paid
Assistant: [Uses subscribe_invoice_status tool]
I'm now monitoring the invoice. I'll notify you when it's paid.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

Architecture

src/
├── index.ts              # MCP server entry point
├── client.ts             # Blink GraphQL client
├── types.ts              # TypeScript type definitions
├── graphql/
│   └── operations.ts     # GraphQL queries, mutations, subscriptions
└── tools/
    ├── wallet.ts         # Wallet and account tools
    ├── lightning.ts      # Lightning Network tools
    ├── onchain.ts        # On-chain Bitcoin tools
    ├── intraledger.ts    # Blink-to-Blink transfer tools
    ├── webhooks.ts       # Webhook and subscription tools
    └── l402.ts           # L402 consumer, producer, and discovery tools

API Reference

This MCP server wraps the Blink GraphQL API. For detailed API documentation, visit:

• Blink Agent Playbook: Canonical AI agent API reference — order of operations, safety constraints, and verification checklist.
• Blink Developer Docs
• Blink API Playground
• llms.txt: Machine-readable discovery metadata for AI agents.

Security Considerations

• API Key Security: Never commit your API key to version control
• Permission Scoping: Use the minimum required permissions for your use case
• Write Operations: Be cautious with write permissions as they allow sending funds
• Environment Variables: Store API keys in environment variables, not in config files

Spend Guard

Because this server holds a Blink API key and exposes tools that move funds, an agent processing untrusted content (a web page, email, invoice memo, etc.) could be steered into making a payment via indirect prompt injection. To mitigate this, every money-moving tool passes through a central spend guard before it executes, enforcing (in order): recipient allowlist → per-transaction cap → rolling 24h budget → human confirmation. Webhook changes (add_webhook, remove_webhook) pass through the same confirmation step.

The guard is safe-by-default: with no configuration, all spend tools and webhook changes require explicit confirmation before running.

Confirmation flow. When the MCP client supports elicitation, the guard prompts inline and blocks until the user accepts — this is the preferred, injection-safe path.

For clients without elicitation support, a token returned through the tool channel is not a human boundary (a prompt-injected loop could simply echo it back), so there is no such token. Instead BLINK_APPROVAL_MODE controls the fallback:

• fail-closed (default): the spend is refused.
• stderr-code: the server prints a one-time approval code to its console (stderr) — which the model cannot read — and the human operator re-issues the tool call with approval_code="<code>". The code never enters model context, so injection alone cannot obtain it.

Amount enforcement. BLINK_MAX_PAYMENT_SATS and BLINK_DAILY_BUDGET_SATS are enforced for every spend tool. Fixed-amount Lightning invoices are decoded from the bolt11 before payment so pay_invoice is subject to the same caps and budget as amount-carrying tools. USD-wallet amounts (send_onchain_usd, send_to_wallet_usd, send_to_username with wallet_currency: "USD") are in cents; when a cap or budget is configured they are converted to sats at Blink's current rate before being checked against it, and refused if the conversion fails. For l402_pay, whose amount is only known after fetching the invoice, the caps are re-checked after decoding and before payment.

The 24h budget is reserved atomically right before a payment executes, so concurrent calls cannot overspend it. The reservation is released when the payment definitely fails (failed attempts never burn budget) and kept when it succeeds — or when the outcome is unknown (e.g. a timeout or a PENDING payment), since the funds may have moved. It is persisted to a 0600 ledger at ~/.blink/spend-ledger.json so it survives restarts; the ledger is locked against concurrent server processes, written atomically, and if it becomes unreadable spends are refused (while a budget is configured) rather than the budget silently resetting. A lock file left behind by a hard-killed process (~/.blink/spend-ledger.json.lock) is never removed automatically; spends are refused with an error naming the file until you delete it.

Sweeps and undecodable amounts. When a per-transaction cap or daily budget is configured, send_onchain_all (full-balance sweep) and any pay_invoice whose bolt11 amount cannot be decoded are refused — the amount cannot be verified against the cap, so the guard fails closed rather than bypassing it. With no caps configured, these still require confirmation.

L402 hardening. l402_pay enforces a mandatory spend cap (max_amount_sats or BLINK_L402_MAX_SATS) plus the global caps above, and refuses invoices whose amount cannot be decoded. Server-side L402 fetches require BLINK_L402_HOST_ALLOWLIST (fail-closed when unset), are HTTPS-only, and reject private, loopback, link-local and other non-public addresses (including IPv4 embedded in IPv6). Redirects are followed manually and every hop of every L402 request (the HEAD probe, the resource GET, and the l402-protocol invoice POST) is re-validated before it is sent; credentials are dropped when a redirect changes origin. Sockets are not pinned to the checked address, so DNS rebinding is not fully closed: the host allowlist limits that exposure to hosts you trust, so only allowlist hosts whose DNS you trust. Cached L402 tokens are stored 0600, and l402_store get masks payment secrets unless called with reveal: true.

Webhooks. A webhook receives a notification for every payment on the account, so registering one is treated like a spend: add_webhook and remove_webhook require human confirmation (same flow as above). add_webhook also requires an HTTPS URL with a DNS hostname (IP literals and localhost are rejected) and, when BLINK_WEBHOOK_ALLOWLIST is set, a listed hostname.

Troubleshooting

"BLINK_API_KEY environment variable is required"

Make sure you've set the BLINK_API_KEY environment variable with your API key.

"GraphQL Error: Not authorized"

Your API key may not have the required permissions. Check your key's scopes in the Blink wallet settings.

WebSocket connection issues

Real-time subscriptions require a stable connection. Check your network and firewall settings.

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Links

• Blink Wallet
• Blink Developer Docs
• Blink Agent Playbook
• Model Context Protocol
• MCP SDK