Bitcoin-MCP

Instructions

Implementation Reference

• src/bitcoin_mcp/server.py:1503-1532 (handler)

  The `get_address_balance` tool is defined here. It attempts to fetch balance data from a configured Satoshi API indexer, falling back to mempool.space if necessary.

  @mcp.tool()
  def get_address_balance(address: str) -> str:
      """Get the total balance, transaction count, and first/last seen times for a Bitcoin address.
  
      Uses the Satoshi API blockchain indexer when available, falls back to mempool.space.
      Returns total received, total sent, current balance, tx count, and timestamps.
  
      Args:
          address: Bitcoin address (any format: legacy, P2SH, bech32, bech32m)
      """
      result = _query_indexed_api(f"address/{address}/balance")
      if "error" not in result:
          return json.dumps(result)
      # Fallback to mempool.space
      data = _query_mempool_space(f"address/{address}")
      if "error" in data:
          return json.dumps(data)
      chain = data.get("chain_stats", {})
      mempool = data.get("mempool_stats", {})
      balance = {
          "source": "mempool.space",
          "address": address,
          "total_received": chain.get("funded_txo_sum", 0),
          "total_sent": chain.get("spent_txo_sum", 0),
          "balance": chain.get("funded_txo_sum", 0) - chain.get("spent_txo_sum", 0),
          "tx_count": chain.get("tx_count", 0),
          "unconfirmed_balance": mempool.get("funded_txo_sum", 0) - mempool.get("spent_txo_sum", 0),
          "unconfirmed_tx_count": mempool.get("tx_count", 0),
      }
      return json.dumps(balance)