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

Related MCP server: RGB Lightning Network MCP Server

Prerequisites

• Node.js 18+

• 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.

The guard is safe-by-default: with no configuration, all spend tools 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. 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 debited only on a successful payment (failed attempts never burn budget) and is persisted to a 0600 ledger at ~/.blink/spend-ledger.json so it survives restarts.

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, reject private/loopback/link-local addresses, and re-validate every redirect hop — mitigating DNS-rebinding SSRF without socket pinning. Cached L402 tokens are stored 0600, and l402_store get masks payment secrets unless called with reveal: true.

Webhooks. add_webhook requires an HTTPS URL 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