AgentBTC

BYON-enabled MCP server that enables non-custodial Bitcoin micropayments for AI agents via the Model Context Protocol. It lets you run a local, self-contained payments processor that interacts directly with your Lightning node, keeping credentials on your machine while monetizing API access and agent actions.

How to use

You use this MCP server with an MCP-compatible client to enable pay-per-use access to AI agent tools. Start the server locally and configure your MCP client or Claude Desktop to point to your local MCP endpoint. The server handles wallet management, invoicing, and Lightning payments, while your Lightning node credentials never leave your machine. Typical usage involves starting the server, verifying connectivity to your node, and then using MCP-enabled agents to perform actions that incur micropayments.

How to install

Prerequisites: ensure you have Node.js 18 or newer and a Lightning node with REST API enabled.

Install the MCP server using a quick start option, then start the server.

Option 1: run without installation using npx

npx agentbtc-mcp start

Option 2: install globally and start

npm install -g agentbtc-mcp
agentbtc-mcp start

Claude Desktop integration requires a local MCP config. Create the following configuration for Claude Desktop so it can start and connect to your local MCP server.

Code snippet for Claude Desktop config (macOS path shown; adjust for your OS):

{
  "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"
      }
    }
  }
}

Configuration and environment

The server uses environment variables to connect to your Lightning node and to configure API access. You can override these values per deployment.

Security and trust model

This MCP server follows a Bring Your Own Node (BYON) model. Your Lightning node credentials stay on your machine, the MCP server runs locally, and no credentials are sent to external servers. Agent wallets can enforce spending limits, and all payments are recorded for auditability.

Troubleshooting

If you encounter issues, verify that your Lightning node REST endpoint is reachable and that the macaroon file path is correct. Ensure you are using the correct network (mainnet vs testnet) and that the MACAROON has the necessary permissions.

Tools and capabilities

The MCP server provides a set of tools to manage agent wallets, payments, and node operations. The available tools include creating and listing agent wallets, generating invoices, paying invoices, decoding invoices, monitoring channels, and accessing L402-protected APIs.

Notes and examples

Key examples include listing agent wallets, creating a new wallet, generating and paying invoices, decoding BOLT11 invoices, and checking channel balances. You can also access APIs protected by L402 to monetize specific endpoints.

Additional resources

This MCP server is designed to run alongside Claude Desktop and other MCP-compatible tools, enabling seamless integration for pay-per-use AI workflows.

Available tools

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