JSPM

agentbtc-mcp

1.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1
  • Score
    100M100P100Q28756F
  • License MIT

BYON Bitcoin payments for AI agents via Model Context Protocol. The world's first Lightning MCP server for Claude Desktop.

Package Exports

  • agentbtc-mcp
  • agentbtc-mcp/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (agentbtc-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

🚀 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

📜 License

MIT — see LICENSE.

Built by BK Block Solutions ⚡