Bitcoin-MCP

Instructions

Implementation Reference

• src/bitcoin_mcp/server.py:1536-1580 (handler)

  Tool handler for 'get_address_history' which queries indexed API or mempool.space for address transaction history.

  def get_address_history(address: str, offset: int = 0, limit: int = 25) -> str:
      """Get paginated transaction history for a Bitcoin address.
  
      Uses the Satoshi API blockchain indexer when available, falls back to mempool.space.
      Shows each transaction with block height, timestamp, and net value change for the address.
      Results are ordered newest-first.
  
      Args:
          address: Bitcoin address (any format)
          offset: Skip this many transactions (for pagination, default 0)
          limit: Max transactions to return (default 25, max 100)
      """
      limit = min(limit, 100)
      result = _query_indexed_api(f"address/{address}/txs?offset={offset}&limit={limit}")
      if "error" not in result:
          return json.dumps(result)
      # Fallback to mempool.space (returns last 50 txs, no offset support)
      txs = _query_mempool_space(f"address/{address}/txs")
      if isinstance(txs, dict) and "error" in txs:
          return json.dumps(txs)
      if not isinstance(txs, list):
          return json.dumps({"error": "Unexpected response from mempool.space"})
      # Apply offset/limit manually
      page = txs[offset:offset + limit]
      history = {
          "source": "mempool.space",
          "address": address,
          "total_available": len(txs),
          "offset": offset,
          "limit": limit,
          "transactions": [
              {
                  "txid": tx.get("txid"),
                  "block_height": tx.get("status", {}).get("block_height"),
                  "block_time": tx.get("status", {}).get("block_time"),
                  "confirmed": tx.get("status", {}).get("confirmed", False),
                  "fee": tx.get("fee"),
                  "size": tx.get("size"),
                  "weight": tx.get("weight"),
              }
              for tx in page
          ],
      }
      return json.dumps(history)