Skip to main content
Glama
Blink MCP Server

Blink MCP Server

Official
by blinkbitcoin

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

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)

Tool

Description

get_account_info

Get current user account information

get_wallets

List all wallets with balances

get_wallet_balance

Get balance of a specific wallet

get_transactions

Get transaction history (paginated)

get_transaction_by_id

Get specific transaction details

get_account_limits

View withdrawal and transfer limits

set_default_wallet

Set default wallet (BTC or USD)

set_display_currency

Set display currency preference

get_realtime_price

Get current Bitcoin price

get_price_history

Get historical price data

convert_currency

Convert between fiat and Bitcoin

get_supported_currencies

List supported currencies

lookup_user_wallet

Find wallet by Blink username

check_username_available

Check username availability

set_username

Set/update your username

get_authorization_scopes

View API key permissions

get_network_info

Get Lightning node info

Lightning Network (12 tools)

Tool

Description

create_invoice

Create BTC Lightning invoice

create_invoice_usd

Create USD-denominated invoice

create_invoice_no_amount

Create open (any amount) invoice

cancel_invoice

Cancel unpaid invoice

get_invoice_status

Check invoice status by hash

get_invoice_status_by_request

Check status by bolt11

pay_invoice

Pay a Lightning invoice

pay_invoice_with_amount

Pay open invoice with amount

pay_lightning_address

Send to Lightning address

pay_lnurl

Pay via LNURL

estimate_lightning_fee

Estimate payment fee

estimate_lightning_fee_no_amount

Estimate fee for open invoice

On-Chain Bitcoin (7 tools)

Tool

Description

create_onchain_address

Generate new receiving address

get_current_onchain_address

Get current address

send_onchain

Send BTC on-chain

send_onchain_all

Sweep entire balance

send_onchain_usd

Send from USD wallet on-chain

estimate_onchain_fee

Estimate BTC transaction fee

estimate_onchain_fee_usd

Estimate USD wallet fee

Tool

Description

send_to_wallet

Send BTC to wallet ID (free, instant)

send_to_wallet_usd

Send USD to wallet ID

send_to_username

Send to Blink username

Webhooks & Subscriptions (9 tools)

Tool

Description

list_webhooks

List registered webhooks

add_webhook

Register webhook endpoint

remove_webhook

Remove webhook

subscribe_invoice_status

Subscribe to invoice updates

subscribe_invoice_status_by_hash

Subscribe by payment hash

subscribe_account_updates

Subscribe to all account events

subscribe_price_updates

Subscribe to price changes

list_subscriptions

List active subscriptions

cancel_subscription

Cancel a subscription

cancel_all_subscriptions

Cancel all subscriptions

L402 Protocol (6 tools)

Tool

Description

l402_discover

Probe a URL for L402 payment requirements (no payment)

l402_pay

Access an L402-protected URL, paying automatically via Blink

l402_store

Manage the L402 token cache (~/.blink/l402-tokens.json)

l402_challenge_create

Create an L402 payment challenge (invoice + signed macaroon)

l402_payment_verify

Verify an L402 payment token (preimage + HMAC signature + caveats)

l402_search

Search L402 service directories (l402.directory or 402index.io)

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:

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.

Variable

Default

Effect

BLINK_REQUIRE_CONFIRMATION

true

Require confirmation before any spend or webhook change

BLINK_APPROVAL_MODE

fail-closed

Fallback when the client can't do elicitation: fail-closed or stderr-code

BLINK_MAX_PAYMENT_SATS

(none)

Per-transaction cap in sats (authoritative for all spends, incl. l402_pay)

BLINK_DAILY_BUDGET_SATS

(none)

Rolling 24h spend cap in sats (durable across restarts)

BLINK_RECIPIENT_ALLOWLIST

(none)

Allowed recipients (ln addr / username / btc addr / wallet id)

BLINK_WEBHOOK_ALLOWLIST

(none)

Allowed webhook callback hostnames

BLINK_L402_MAX_SATS

1000

Mandatory default cap for l402_pay

BLINK_L402_HOST_ALLOWLIST

(none)

Required for L402 network access; fail-closed when unset

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

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.

Available Tools

55 tools
add_webhookB

Register a new webhook callback endpoint to receive payment notifications

Inputs: url (required).

cancel_all_subscriptionsA

Cancel all active real-time subscriptions

Inputs: no named parameters.

cancel_invoiceA

Cancel an unpaid Lightning invoice

Inputs: wallet_id (required), payment_hash (required).

cancel_subscriptionB

Cancel an active real-time subscription

Inputs: subscription_id (required).

check_username_availableA

Check if a Blink username is available

Inputs: username (required).

convert_currencyC

Get currency conversion estimation between fiat and Bitcoin

Inputs: amount (required), currency (required).

create_invoiceB

Create a Lightning invoice to receive a specific amount of Bitcoin. Amount is in satoshis for BTC wallet.

Inputs: amount (required), wallet_id (required), memo, expires_in, +1 more.

create_invoice_no_amountA

Create a Lightning invoice without a specified amount (open invoice). The payer can choose how much to send.

Inputs: wallet_id (required), memo, expires_in, external_id.

create_invoice_usdA

Create a Lightning invoice to receive a specific amount in USD cents (Stablesats). The invoice will be denominated in satoshis but credited as USD.

Inputs: amount (required), wallet_id (required), memo, expires_in, +1 more.

create_onchain_addressA

Generate a new on-chain Bitcoin address to receive funds

Inputs: wallet_id (required).

estimate_lightning_feeA

Estimate the Lightning network fee for paying an invoice

Inputs: wallet_id (required), payment_request (required).

estimate_lightning_fee_no_amountB

Estimate the Lightning network fee for paying an open (no-amount) invoice

Inputs: amount (required), wallet_id (required), payment_request (required).

estimate_onchain_feeB

Estimate the on-chain transaction fee for sending Bitcoin (BTC wallet)

Inputs: amount (required), address (required), wallet_id (required), speed.

estimate_onchain_fee_usdA

Estimate the on-chain transaction fee for sending from USD wallet

Inputs: amount (required), address (required), wallet_id (required), speed.

get_account_infoA

Get the current user account information including wallets, balances, and settings

Inputs: no named parameters.

get_account_limitsA

Get the current account limits for withdrawals, internal sends, and currency conversion

Inputs: no named parameters.

get_authorization_scopesA

Get the permission scopes available for the current API key

Inputs: no named parameters.

get_current_onchain_addressA

Get the current (most recent) on-chain Bitcoin address for a wallet

Inputs: wallet_id (required).

get_invoice_statusA

Check the payment status of a Lightning invoice by payment hash

Inputs: payment_hash (required).

get_invoice_status_by_requestA

Check the payment status of a Lightning invoice by payment request (bolt11)

Inputs: payment_request (required).

get_network_infoA

Get global network information including Lightning node details and fee information

Inputs: no named parameters.

get_price_historyA

Get Bitcoin price history for a specified time range

Inputs: range (required).

get_realtime_priceA

Get the current real-time Bitcoin price in a specified currency

Inputs: currency.

get_supported_currenciesB

Get list of all supported display currencies

Inputs: no named parameters.

get_transaction_by_idB

Get details of a specific transaction by ID

Inputs: wallet_id (required), transaction_id (required).

get_transactionsB

Get transaction history for one or more wallets. Supports pagination.

Inputs: limit, cursor, wallet_ids.

get_wallet_balanceA

Get the balance of a specific wallet by ID. Returns balance in satoshis (BTC) or cents (USD).

Inputs: wallet_id (required).

get_walletsA

Get all wallets (BTC and USD) with their current balances. Balance is in satoshis for BTC wallet and cents for USD wallet.

Inputs: no named parameters.

l402_challenge_createA

Create an L402 payment challenge (invoice + signed macaroon) to protect a resource behind a Lightning paywall. Returns a WWW-Authenticate header that can be sent to clients with HTTP 402.

Inputs: amount_sats (required), memo, resource, wallet_id, +1 more.

l402_discoverA

Probe a URL for L402 payment requirements without paying. Returns the invoice, price in sats, and format (lightning-labs or l402-protocol). Use this before l402_pay to check the cost of accessing a resource.

Inputs: url (required), method.

l402_payA

Access an L402-protected URL by automatically paying the Lightning invoice. Checks the token cache first to avoid re-paying. Returns the response data from the protected resource after successful payment.

Inputs: url (required), wallet_id (required), force, method, +2 more.

l402_payment_verifyA

Verify an L402 payment token submitted by a client. Checks three layers: 1) preimage proves payment (SHA-256), 2) HMAC signature proves authenticity, 3) caveats (expiry, resource) are satisfied. Returns valid: true/false.

Inputs: token, macaroon, preimage, resource.

l402_storeA

Manage the local L402 token cache at ~/.blink/l402-tokens.json. List cached tokens (with masked sensitive data), get a token for a domain, or clear tokens.

Inputs: command (required), domain, reveal, expired_only.

list_subscriptionsA

List all active real-time subscriptions

Inputs: no named parameters.

list_webhooksA

List all registered webhook callback endpoints for the account

Inputs: no named parameters.

lookup_user_walletB

Look up a user's default wallet by their Blink username

Inputs: username (required), wallet_currency.

pay_invoiceB

Pay a Lightning invoice. The invoice amount must be specified in the invoice.

Inputs: wallet_id (required), payment_request (required), memo.

pay_invoice_with_amountB

Pay a Lightning invoice that has no amount specified (open invoice). You specify the amount to send.

Inputs: amount (required), wallet_id (required), payment_request (required), memo.

pay_lightning_addressC

Send Bitcoin to a Lightning Address (e.g., user@blink.sv)

Inputs: amount (required), wallet_id (required), ln_address (required).

pay_lnurlC

Pay using an LNURL (Lightning URL)

Inputs: lnurl (required), amount (required), wallet_id (required).

remove_webhookB

Remove a registered webhook callback endpoint

Inputs: id (required).

send_onchainC

Send Bitcoin on-chain to a Bitcoin address. Amount is in satoshis for BTC wallet.

Inputs: amount (required), address (required), wallet_id (required), memo, +1 more.

send_onchain_allB

Send the entire wallet balance on-chain to a Bitcoin address (sweep)

Inputs: address (required), wallet_id (required), memo, speed.

send_onchain_usdC

Send on-chain Bitcoin from a USD (Stablesats) wallet. Amount is in cents.

Inputs: amount (required), address (required), wallet_id (required), memo, +1 more.

send_to_usernameA

Send Bitcoin to a Blink user by their username. This looks up their wallet and does an intraledger transfer (free, instant).

Inputs: amount (required), username (required), wallet_id (required), memo, +1 more.

send_to_walletA

Send Bitcoin directly to another Blink wallet (free, instant, intraledger transfer). Amount is in satoshis for BTC wallets.

Inputs: amount (required), wallet_id (required), recipient_wallet_id (required), memo.

send_to_wallet_usdA

Send USD (Stablesats) directly to another Blink wallet (free, instant, intraledger transfer). Amount is in cents.

Inputs: amount (required), wallet_id (required), recipient_wallet_id (required), memo.

set_default_walletA

Set the default wallet for the account (BTC or USD wallet)

Inputs: wallet_id (required).

set_display_currencyB

Set the display currency for the account (e.g., USD, EUR, BTC)

Inputs: currency (required).

set_usernameA

Set or update the username for the current user

Inputs: username (required).

subscribe_account_updatesA

Subscribe to all real-time account updates including incoming/outgoing transactions and price updates

Inputs: no named parameters.

subscribe_invoice_statusC

Subscribe to real-time updates for a Lightning invoice payment status. Returns a subscription ID to track or cancel.

Inputs: payment_request (required).

subscribe_invoice_status_by_hashB

Subscribe to real-time updates for a Lightning invoice by payment hash

Inputs: payment_hash (required).

subscribe_price_updatesC

Subscribe to real-time Bitcoin price updates in a specified currency

Inputs: currency.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 55 tools

    Disambiguation3/5

    The BTC/USD tool pairs (send_onchain vs send_onchain_usd, send_to_wallet vs send_to_wallet_usd, estimate_onchain_fee vs estimate_onchain_fee_usd, create_invoice vs create_invoice_usd) and the invoice-status quartet (get_invoice_status, get_invoice_status_by_request, subscribe_invoice_status, subscribe_invoice_status_by_hash) create real selection friction. Descriptions do a decent job of explaining the differences, but an agent must read carefully to avoid picking the wrong variant. Multi-mode tools like l402_store (list/get/clear in one) add further ambiguity.

    Naming Consistency3/5

    Mostly snake_case verb_noun with a coherent variant-suffix scheme (_usd, _no_amount, _by_request, _by_hash, _all), which is readable. However the l402_ family is noun-prefixed with non-verb names (l402_discover, l402_store, l402_challenge_create) and a few tools use different molds (check_username_available, lookup_user_wallet), so it's mixed rather than uniform.

    Tool Count2/5

    55 tools is well above what a wallet API surface needs; many are near-duplicates that could be collapsed into one tool with a wallet/currency parameter (all the *_usd variants, the three create_invoice variants, the four estimate_*_fee tools). The L402 and subscription families are legitimate, but the BTC/USD duplication inflates the count significantly.

    Completeness4/5

    Coverage is strong: receive (invoices, on-chain addresses), send (invoice, LNURL, lightning address, intraledger, on-chain sweep), fees, webhooks, real-time subscriptions, account settings, and a full L402 client+server flow. Minor gaps exist — no explicit USD-wallet invoice payment tool (create_invoice_usd has no pay counterpart), no webhook get/update-by-id, and no contacts directory.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      F
      maintenance
      Enables interaction with lightning addresses and common lightning tools via your LLM, providing Lightning Network functionality through natural language.
      3
      13 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with RGB assets, Lightning Network operations, and Bitcoin transactions through RGB Lightning Node APIs. Supports asset management, invoice creation/payment, channel management, on-chain transactions, and asset swaps.
      18
      10 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Lightning Network wallet operations through the Breez SDK, allowing users to check balances, send/receive payments, create invoices, and manage Bitcoin Lightning transactions via natural language.
      7
      MIT