README.md
AgentBTC MCP Server
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:
- Your Lightning node credentials stay on your machine
- The MCP server runs locally, connecting directly to your node
- No credentials are ever transmitted to AgentBTC servers
- Agent wallets have configurable spending limits
- 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— usuallylocalhost:8080for LND REST - For Voltage nodes: use
your-node.t.voltageapp.io:8080
"Permission denied"
- Check macaroon file exists and is readable
- Use
readonly.macaroonfor safety
"Invalid macaroon"
- Ensure you're using the correct network (mainnet vs testnet)
- Try copying the macaroon to a new path
🌐 Links
- Website: agentbtc.io
- GitHub: github.com/bkblock/agentbtc-mcp
📜 License
MIT — see LICENSE.
Built by BK Block Solutions ⚡
Tools 13
list_agent_walletsList all agent walletsget_agent_balanceCheck wallet balancecreate_agent_walletCreate a new agent walletdelete_agent_walletRemove an agent walletget_node_infoLightning node statuscreate_lightning_invoiceGenerate payment requestspay_lightning_invoiceSend Lightning paymentssend_to_lightning_addressPay Lightning addressesdecode_invoiceDecode BOLT11 invoicescheck_channel_balanceChannel liquidity infolist_channelsList Lightning channelsget_transaction_historyPayment historyaccess_l402_apiAccess L402-protected APIsEnvironment Variables
AGENTBTC_LND_HOSTrequiredLND REST API endpointAGENTBTC_LND_MACAROONrequiredPath to LND macaroon fileAGENTBTC_API_URLAgentBTC server URLAGENTBTC_API_KEYYour owner API key for wallet managementTry it
→Check the current balance of my agent wallet.
→Create a new Lightning invoice for 5000 sats.
→Pay this Lightning invoice: [invoice_string].
→List my current Lightning channels and check their liquidity.
→Access the L402-protected API at [url] using my wallet.