bsl-agent-mcp

MCP server that lets an AI agent (Claude Desktop, Claude Code, or any MCP client) operate a user-owned wallet on the Bitcoin-IPC testnet: deposit L1 BTC into subnet1, pay wBTC within subnet1 or across to subnet2, and fetch the Bitcoin-anchored receipt for any payment. The agent never holds keys — it can only request operations; the server signs locally and refuses any deposit or payment above SPEND_CAP_SATS until the user explicitly approves it (confirmed=true).

Disclaimer: this code is not audited and is meant for testnet use only. Do not use it with mainnet funds or keys that control real value.

Tools

Requirements

A running bsl-client container — the public image is ghcr.io/bitcoinscalinglabs/bsl-client:testnet — with its bsl.env configuration file, which must also contain AGENT_PRIVATE_KEY (the EVM key the server pays from).

Run with Docker

The image runs next to bsl-client and shares its network; the entrypoint generates the ipc-cli config, imports AGENT_PRIVATE_KEY, runs connectivity checks, and idles.

docker build -t ghcr.io/bitcoinscalinglabs/bsl-agent-mcp:testnet .

docker run -d --env-file ./bsl.env \
  --network container:bsl-client \
  --name bsl-agent-mcp \
  ghcr.io/bitcoinscalinglabs/bsl-agent-mcp:testnet
docker logs bsl-agent-mcp   # should end with "bsl-agent-mcp ready"

Claude Desktop attaches MCP sessions to the standing container:

{
  "mcpServers": {
    "bsl-payments": {
      "command": "docker",
      "args": ["exec", "-i", "bsl-agent-mcp", "node", "/app/dist/index.js"]
    }
  }
}

Run from source (development)

Node.js ≥ 20. The bsl-client container must publish the provider port (-p 127.0.0.1:3030:3030) and have the agent key imported once:

docker exec bsl-client ipc-cli wallet import --wallet-type evm --private-key <key>

npm install && npm run build
cp .env.example .env        # fill in

Claude Desktop config: "command": "node", "args": ["/ABS/PATH/bsl-agent-mcp/dist/index.js"]. Configuration comes from the repo's .env; an env block in the Desktop config takes precedence.

Configuration

Notes

• Amounts are satoshis everywhere (1 BTC = 100,000,000 sats); wBTC has 18 decimals and the server converts internally.

• Recipients are either payees from the built-in address book or addresses supplied by the user; the agent is instructed never to invent an address.