AgenticBTC - Bitcoin Lightning MCP Server

🚀 Enable Claude Desktop to send Bitcoin payments, access L402 APIs, and manage Lightning wallets.

AgenticBTC provides a Model Context Protocol (MCP) server that gives Claude Desktop direct access to Bitcoin and Lightning Network functionality. Your AI assistant can now make payments, create wallets, and interact with Lightning-powered APIs automatically.

⚡ Quick Start

# Install and setup in one command
npx agenticbtc setup

# Check if everything is working
npx agenticbtc status

Then restart Claude Desktop and start using Bitcoin with your AI assistant!

🎯 What It Does

• 💰 Wallet Management: Create and check Bitcoin wallets for AI agents
• ⚡ Lightning Payments: Send instant, low-fee Bitcoin payments via Lightning Network
• 🔐 L402 APIs: Access premium APIs that charge per request using Lightning micropayments
• 📊 Node Management: Monitor Lightning node status and connectivity
• 🤖 Claude Integration: Seamless setup with Claude Desktop's MCP system

🛠️ Installation

Method 1: NPX (Recommended)

npx agentbtc setup

Method 2: Global Install

npm install -g agentbtc
agentbtc setup

📋 Prerequisites

1. AgentBTC API Server - Running at http://localhost:8000 or custom URL
2. API Key - From your AgentBTC server
3. Lightning Node (Optional) - For L402 API access and direct payments

🔧 Configuration

Interactive Setup

npx agentbtc setup

This will ask for:

• API URL (default: http://localhost:8000)
• API Key (required)
• Lightning Node Host (optional, for L402 APIs)
• LND Macaroon (optional, hex format)

Manual Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "agentbtc": {
      "command": "npx",
      "args": ["agentbtc", "server"],
      "env": {
        "AGENTBTC_API_URL": "http://localhost:8000",
        "AGENTBTC_API_KEY": "your-api-key",
        "AGENTBTC_LND_HOST": "https://your-lnd-node:8080",
        "AGENTBTC_LND_MACAROON": "your-lnd-macaroon-hex",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

🎮 Usage Examples

Once configured, you can ask Claude Desktop:

Basic Wallet Operations

"Create a Bitcoin wallet called 'my-assistant'"
"Check the balance of agent wallet abc123"

Lightning Payments

"Pay this Lightning invoice: lnbc..."
"Send 1000 sats to this invoice with a 50 sat fee limit"

L402 API Access

"Get Bitcoin market data using L402"
"Access the premium AI service API"
"Show me data from the L402 protected endpoint"

Node Information

"Show my Lightning node status"
"Get node info and channel count"

🔍 Commands

| Command | Description | |---------|-------------| | agentbtc setup | Interactive setup for Claude Desktop | | agentbtc server | Start MCP server (used internally by Claude) | | agentbtc status | Check configuration and connectivity | | agentbtc --help | Show help information |

🌍 Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | AGENTBTC_API_URL | AgentBTC API endpoint | http://localhost:8000 | | AGENTBTC_API_KEY | AgentBTC API key | Required | | AGENTBTC_LND_HOST | Lightning node REST API | Optional | | AGENTBTC_LND_MACAROON | LND macaroon (hex format) | Optional | | NODE_TLS_REJECT_UNAUTHORIZED | Skip TLS verification | 0 |

🔧 Troubleshooting

Check Status

npx agentbtc status

Common Issues

❌ API Connection Failed

• Verify your AgentBTC server is running
• Check the API URL and key
• Ensure firewall allows connections

❌ Lightning Node Connection Failed

• Verify LND REST API is accessible
• Check macaroon permissions (needs invoices:read, invoices:write)
• Confirm TLS certificates if using HTTPS

❌ Claude Desktop Not Loading Server

• Restart Claude Desktop after setup
• Check claude_desktop_config.json syntax
• Verify file permissions

Config File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

🏗️ Development

Local Testing

git clone <repo>
cd agentbtc/npm-package
node bin/agentbtc.js --help
node bin/agentbtc.js status

Project Structure

agentbtc/
├── bin/
│   └── agentbtc.js          # CLI entry point
├── src/
│   └── server.js            # MCP server implementation  
├── package.json
└── README.md

📝 License

MIT License - see LICENSE file for details.

🔗 Links

• Repository: https://github.com/agentbtc/agentbtc
• Issues: https://github.com/agentbtc/agentbtc/issues
• Model Context Protocol: https://modelcontextprotocol.io
• Claude Desktop: https://claude.ai/desktop

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🎉 Ready to give your AI assistant Bitcoin superpowers?

npx agentbtc setup