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 ⚡