Skip to main content
Glama
Sign In
AgentBTC MCP Server

AgentBTC MCP Server

by bkblocksolutions-rgb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

AgentBTC MCP Server

npm version License: MIT

BYON (Bring Your Own Node) Bitcoin payments for AI agents via Model Context Protocol

The world's first Bitcoin/Lightning MCP server. Your Lightning node credentials never leave your machine. Works with Claude Desktop, OpenClaw, and any MCP-compatible AI tool.

🌟 Features

  • 🔒 True BYON: Your Lightning credentials never leave your machine — zero-trust architecture

  • ⚡ Lightning Network: Fast, cheap Bitcoin micropayments (~200ms per payment)

  • 🤖 13 MCP Tools: Complete wallet management, payments, invoices, channels, and L402

  • 📊 L402 Protocol: HTTP 402 "Payment Required" for API monetization

  • 🛡️ Non-Custodial: Zero counterparty risk — you control your Bitcoin

  • 🏷️ Lightning Addresses: Send to bot@yourname.agentbtc.io

  • 💳 Spending Policies: Per-transaction, daily, and monthly limits for agent wallets

Related MCP server: Alby Bitcoin Payments MCP Server

🚀 Quick Start

Option 1: npx (no install)

npx agentbtc-mcp start

Option 2: Global install

npm install -g agentbtc-mcp
agentbtc-mcp start

Claude Desktop Config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentbtc": {
      "command": "npx",
      "args": ["-y", "agentbtc-mcp", "start"],
      "env": {
        "AGENTBTC_LND_HOST": "your-node:8080",
        "AGENTBTC_LND_MACAROON": "/path/to/readonly.macaroon",
        "AGENTBTC_API_URL": "https://agentbtc.io",
        "AGENTBTC_API_KEY": "your-api-key"
      }
    }
  }
}

🔧 Available Tools (13)

Tool

Description

list_agent_wallets

List all agent wallets

get_agent_balance

Check wallet balance

create_agent_wallet

Create a new agent wallet

delete_agent_wallet

Remove an agent wallet

get_node_info

Lightning node status

create_lightning_invoice

Generate payment requests

pay_lightning_invoice

Send Lightning payments

send_to_lightning_address

Pay Lightning addresses

decode_invoice

Decode BOLT11 invoices

check_channel_balance

Channel liquidity info

list_channels

List Lightning channels

get_transaction_history

Payment history

access_l402_api

Access L402-protected APIs

⚙️ Configuration

Environment Variables

Variable

Required

Description

AGENTBTC_LND_HOST

Yes

LND REST API endpoint (e.g., localhost:8080)

AGENTBTC_LND_MACAROON

Yes

Path to LND macaroon file

AGENTBTC_API_URL

No

AgentBTC server URL (default: http://localhost:8000)

AGENTBTC_API_KEY

No

Your owner API key for wallet management

CLI Commands

agentbtc-mcp start          # Start MCP server
agentbtc-mcp setup          # Interactive Claude Desktop setup
agentbtc-mcp test           # Test Lightning node connection
agentbtc-mcp config         # Show current configuration
agentbtc-mcp version        # Show version

📋 Requirements

  • Node.js 18+

  • Lightning Node — LND with REST API enabled

  • MCP Client — Claude Desktop, OpenClaw, or compatible

🔒 Security Model

AgentBTC uses a BYON (Bring Your Own Node) architecture:

  1. Your Lightning node credentials stay on your machine

  2. The MCP server runs locally, connecting directly to your node

  3. No credentials are ever transmitted to AgentBTC servers

  4. Agent wallets have configurable spending limits

  5. All payments are logged with full audit trail

🧪 Testing

# Test with testnet
export AGENTBTC_LND_HOST=your-testnet-node:8080
export AGENTBTC_LND_MACAROON=/path/to/testnet/readonly.macaroon
agentbtc-mcp test

🆘 Troubleshooting

"Connection refused"

  • Verify your Lightning node is running

  • Check AGENTBTC_LND_HOST — usually localhost:8080 for LND REST

  • For Voltage nodes: use your-node.t.voltageapp.io:8080

"Permission denied"

  • Check macaroon file exists and is readable

  • Use readonly.macaroon for safety

"Invalid macaroon"

  • Ensure you're using the correct network (mainnet vs testnet)

  • Try copying the macaroon to a new path

🌐 Links

📜 License

MIT — see LICENSE.

Built by BK Block Solutions ⚡

Available Tools

13 tools
access_l402_apiC

Access an L402-protected API endpoint with automatic Lightning payment

Inputs: endpoint (required), symbol.

check_channel_balanceB

Check available Lightning channel balance (outbound and inbound liquidity)

Inputs: no named parameters.

create_agent_walletA

Create a new Bitcoin wallet for an AI agent (owner access required)

Inputs: agent_name (required).

create_lightning_invoiceC

Create a Lightning Network invoice to receive Bitcoin payments

Inputs: amount_sats (required), description, agent.

decode_invoiceA

Decode a Lightning invoice to inspect amount, expiry, destination before paying

Inputs: invoice (required).

delete_agent_walletB

Delete an agent wallet by name or ID (owner access required)

Inputs: agent (required).

get_agent_balanceC

Get Bitcoin balance for an agent wallet

Inputs: agent_id (required).

get_node_infoB

Get Lightning node connection status and info

Inputs: no named parameters.

get_transaction_historyC

Get recent Lightning payment history

Inputs: max_payments.

list_agent_walletsB

List all agent wallets with their balances and status (agent key: own wallet only)

Inputs: no named parameters.

list_channelsA

List all Lightning channels with capacity, balance, and peer info

Inputs: no named parameters.

pay_lightning_invoiceB

Pay a Lightning Network invoice using agent wallet funds

Inputs: invoice (required), agent, fee_limit_sats.

send_to_lightning_addressB

Send sats to a Lightning address (user@domain.com) using LNURL-pay protocol

Inputs: address (required), amount_sats (required), agent, comment.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap. For example, create_lightning_invoice is for receiving payments, pay_lightning_invoice is for sending payments, and decode_invoice is for inspection, making misselection unlikely. The separation between wallet management (create_agent_wallet, delete_agent_wallet), balance/status queries (get_agent_balance, check_channel_balance), and payment operations is well-defined.

    Naming Consistency4/5

    The naming follows a consistent verb_noun pattern with snake_case throughout, such as create_lightning_invoice and get_agent_balance. There is one minor deviation: access_l402_api uses an acronym (L402) instead of a full noun, but this is understandable given the technical context and does not break the overall pattern.

    Tool Count5/5

    With 13 tools, the count is well-scoped for a Bitcoin/Lightning server, covering key areas like wallet management, payments, and network status. Each tool earns its place by addressing specific needs in the domain, such as creating invoices, checking balances, and managing channels, without being excessive or sparse.

    Completeness5/5

    The tool set provides complete coverage for Bitcoin and Lightning Network operations, including CRUD for wallets (create, list, get balance, delete), payment lifecycle (create invoice, decode, pay, send via address), and network monitoring (node info, channel list, transaction history). No obvious gaps exist for core workflows in this domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Lightning Tools MCP Server

      getAlby
      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
      7 npm
      1
      MIT

    • Maximum Sats MCP

      joelklabo
      A
      license
      A
      quality
      D
      maintenance
      Provides tools for AI agents to access Bitcoin, Lightning Network, and Nostr knowledge, including real-time network statistics and Web of Trust reputation data. It features an integrated Lightning Network payment system for micro-transactions and query-based interactions.
      12
      6 npm
      2
      MIT