Bitcoin wallet MCP server

⚠️ Warning: Experimental. Not yet safe for meaningful funds. Use only with wallets you are prepared to lose. The code is not battle-tested, audited, or hardened. This doc covers setup, configuration, running, and the full tool reference.

Intro

This repo is a single MCP server that exposes Bitcoin (Layer 1) and Stacks (Layer 2) wallet operations as tools. Agents or other MCP clients connect over stdio, pass tool names and arguments as JSON, and get back structured results. The server wraps local Python wallet code and external APIs (mempool.space, Hiro, CoinGecko, etc.). Destructive actions (send, sign-and-broadcast, deploy) support dry_run and do not broadcast by default. No keys or mnemonics are ever returned.

What it exposes: 93 tools in two groups.

1. Layer 1 (Bitcoin): addresses, balance (confirmed and unconfirmed), UTXOs, fee estimation, single and multi-recipient sends, sweep, PSBT sign/decode, message sign/verify, Ordinals / inscriptions, inscription creation, transaction history and RBF, Ledger (Bitcoin app).

2. Layer 2 (Stacks): STX addresses and balances, nonce, STX and token transfers, Clarity call/deploy/read, signing, swaps (Alex, Bitflow, Velar), sBTC bridge, stacking, BNS, market and portfolio data, Ledger (Stacks app), enhanced transaction queries with filtering, mempool monitoring, block explorer, contract event monitoring, token metadata (SIP-10/SIP-9), and network statistics. One mnemonic or WIF key drives both layers; Stacks keys are derived from the same seed.

Table of contents

• Intro

• Overview

• Requirements

• Installation

• Configuration

• Running the server

• Architecture

• Tools reference

  • Layer 1 (Bitcoin)

    • Core Bitcoin

    • Ordinals & inscriptions

    • Inscription creation & onramp

    • Transaction & wallet management

    • Ledger hardware wallet (Bitcoin)

  • Layer 2 (Stacks)

    • Stacks (STX)

    • Swaps, DeFi & bridge

    • BNS & market data

    • Ledger hardware wallet (Stacks)

    • Enhanced transaction queries

    • Mempool operations

    • Block explorer

    • Contract event monitoring

    • Token metadata

    • Network statistics & health

• Security

• Testing

• Troubleshooting

• Reference

• Related documents

Overview

• Purpose: Layer 1 (Bitcoin) and Layer 2 (Stacks) wallet operations as MCP tools with a single, safe interface.

• Design: Destructive operations support dry_run (default true). Responses: { "success": true, ... } or { "success": false, "error": "..." }. No keys or mnemonics in responses.

Requirements

• Python: 3.10 or later (for type hints and runtime).

• OS: Any platform supported by Python and the dependencies (Linux, macOS, Windows). Ledger tools require a Ledger device and USB (or Speculos with interface: "tcp").

• Dependencies: Listed in requirements.txt; install with pip install -r requirements.txt (see Installation).

Installation

1. Clone the repo. If you did not use --recurse-submodules, run git submodule update --init foundation.

2. Create a virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment: Copy .env.example to .env and set at least one key source and network (see Configuration).

5. Optional: If you use the repo’s run_btc_wallet_mcp.sh, it will prefer ../../execution/venv when present; otherwise it uses python3 from PATH.

Configuration

Configuration comes from environment variables. The runner script loads .env from the repository root (two levels above this directory). You can also set variables in the shell or in your MCP host.

Key material (choose one)

Stacks (STX) keys are derived from the same mnemonic using the Stacks path m/44'/5757'/0'/0/0.

Network and safety

Limits (optional)

Fee behavior

Running the server

• Wrapper script (recommended): run_btc_wallet_mcp.sh loads .env from repo root, uses execution/venv/bin/python3 if present else python3, runs the server over stdio.

• Direct: Set env from .env, then run python3 bitcoin_wallet_mcp_server.py from this directory.

Cursor MCP config

Add to .cursor/mcp.json (or your Cursor MCP config file):

{
  "mcpServers": {
    "bitcoin-wallet": {
      "command": "/absolute/path/to/repo/mcp/btc_wallet/run_btc_wallet_mcp.sh"
    }
  }
}

Use an absolute path to your repo. The server lives in mcp/btc_wallet/. Put .env at repo root if you use the script’s env loading.

Architecture

• Entrypoint: bitcoin_wallet_mcp_server.py. Single MCP server; registers all tools and delegates to wallet modules.

• Layer 1 (Bitcoin) modules: bitcoin_wallet.py (addresses, accounts, balance, sends, PSBT, message signing, fees, UTXOs); ord_wallet.py (ordinals and inscriptions); inscribe_onramp_wallet.py (inscription creation, buy quotes); advanced_wallet.py (transaction history, RBF, wallet network, enhanced STX transaction queries, network statistics); ledger_wallet.py (Ledger Bitcoin app).

• Layer 2 (Stacks) modules: stx_wallet.py (addresses, accounts, balance, STX/token transfers, contracts, signing); defi_wallet.py (swaps via Alex, Bitflow, Velar; sBTC bridge; stacking with enhanced cycle metrics); bns_market_wallet.py (BNS, market, portfolio); stx_mempool.py (mempool monitoring and statistics); stx_explorer.py (block explorer queries); stx_events.py (contract event monitoring); stx_token_metadata.py (SIP-10/SIP-9 token metadata); ledger_wallet.py (Ledger Stacks app).

Responses: JSON with "success": true and data, or "success": false and "error". Keys and mnemonics are never returned.

Tools reference

93 tools, grouped by Layer 1 (Bitcoin) and Layer 2 (Stacks). Parameters and response shape are below; optional args can be omitted. dry_run defaults to BTC_DRY_RUN (usually true).

Layer 1 (Bitcoin)

Tools for the Bitcoin chain: addresses, balance, transfers, PSBT, message signing, fees, UTXOs, ordinals, inscription creation, transaction management, and Ledger (Bitcoin app).

Core Bitcoin

Address and account management, balance, prices, transfers, PSBT, message signing, fees, UTXOs.

Parameters: None.

Example response (btc_get_addresses):

{
  "success": true,
  "addresses": [
    {
      "symbol": "BTC",
      "type": "p2wpkh",
      "address": "bc1q...",
      "publicKey": "02abc...",
      "derivationPath": "m/84'/0'/0'/0/0",
      "label": "bip84_p2wpkh_0"
    }
  ],
  "network": "mainnet"
}

Parameters: None.

Example response (btc_wallet_get_balance): { "success": true, "balance_btc": "0.12345678", "network": "testnet" }
Example response (btc_wallet_get_prices): { "success": true, "usd": "91000.12", "eur": "84000.34" }

Parameters (preview): to_address (required), amount_btc or amount_eur (one required).
Parameters (send): to_address (required), amount_btc or amount_eur (one required), optional max_fee_sats, memo, dry_run.

Parameters (btc_send_transfer): recipients (array of { "address", "amount_sats" }), optional max_fee_sats, memo, dry_run.
Parameters (btc_send_max): to_address (required), optional fee_rate, dry_run.
Parameters (btc_combine_utxos): optional to_address, fee_rate, dry_run.

Example request (btc_send_transfer):

{
  "recipients": [
    { "address": "bc1q...", "amount_sats": 50000 },
    { "address": "bc1q...", "amount_sats": 30000 }
  ],
  "dry_run": true
}

Example response: { "success": true, "txid": "DRYRUN_...", "num_recipients": 2, "dry_run": true, "network": "testnet" }

Parameters (btc_sign_psbt): psbt (hex or base64), optional sign_at_index (array of input indices), broadcast, dry_run.
Parameters (btc_sign_batch_psbt): psbts (array of PSBT strings), optional broadcast.
Parameters (btc_decode_psbt): psbt.

Example response (btc_decode_psbt): { "success": true, "num_inputs": 2, "num_outputs": 3, "total_input_sats": 150000, "has_witness_utxo": true, "is_finalized": false, "size_bytes": 512 }

Parameters (sign): message, optional protocol (ecdsa | BIP-322), address_type (e.g. p2wpkh).
Parameters (verify): message, signature, address.

Example response (sign): { "success": true, "signature": "H...", "address": "bc1q...", "message": "Hello, world!", "protocol": "ecdsa" }

Parameters (btc_estimate_fee): num_inputs, num_outputs, address_type (e.g. p2wpkh), optional fee_tier.

Example response (btc_get_fees): { "success": true, "fastest_sat_per_vb": 25, "half_hour_sat_per_vb": 18, "hour_sat_per_vb": 12, "economy_sat_per_vb": 5, "minimum_sat_per_vb": 1, "network": "mainnet", "source": "mempool.space" }

Parameters (btc_list_utxos): optional address_type, min_value_sats, confirmed_only.
Parameters (btc_get_utxo_details): txid, vout.

Example response (btc_list_utxos): { "success": true, "utxos": [{ "txid": "...", "vout": 0, "value_sats": 50000, "value_btc": "0.00050000", "confirmed": true, "address": "bc1q...", "address_type": "p2wpkh" }], "count": 1, "total_sats": 50000, "total_btc": "0.00050000" }

Ordinals & inscriptions

Uses Hiro Ordinals API for inscription data; taproot (P2TR) for ordinals storage; P2WPKH for fee funding.

Parameters (ord_get_inscriptions): optional offset, limit.
Parameters (ord_get_inscription_details): inscription_id.

Parameters (send tools): transfers (array of { "address", "inscriptionId" }), optional dry_run.
Parameters (ord_extract_from_utxo): outpoint (txid:vout), optional dry_run.
Parameters (recover tools): optional dry_run.

Inscription creation & onramp

Parameters (ord_create_inscription): content_type, content (text or hex if content_encoding: hex), optional content_encoding, dry_run.
Parameters (ord_create_repeat_inscriptions): content_type, contents (array), optional dry_run.
Parameters (buy_get_providers): optional crypto, fiat.
Parameters (buy_get_quote): crypto, fiat, fiat_amount (or equivalent).

Transaction & wallet management

Parameters (tx_get_history): optional chain (btc | stx | both), limit.
Parameters (tx_get_status): txid, chain (btc | stx).
Parameters (tx_speed_up, tx_cancel): txid, optional dry_run.
Parameters (wallet_switch_network): network (mainnet | testnet).
Parameters (wallet_add_network): name, btc_api_url, and other endpoint fields as needed.

Ledger hardware wallet (Bitcoin)

Requires a Ledger device connected via USB with the Bitcoin app open. Use interface: "tcp" for Speculos.

Parameters: account (optional), display (optional, show on device), interface (hid or tcp for Speculos).
Parameters (sign PSBT): psbt, interface.

Layer 2 (Stacks)

Tools for the Stacks chain: STX addresses, balance, transfers, contracts, swaps, sBTC bridge, stacking, BNS, market/portfolio data, and Ledger (Stacks app).

Stacks (STX)

Keys are derived from BTC_MNEMONIC using path m/44'/5757'/0'/0/0. Hiro Stacks API is used for chain data and broadcasting.

Parameters (stx_get_balance): optional address.

Example response (stx_get_balance): { "success": true, "address": "SP...", "balance_ustx": 5000000, "balance_stx": "5.000000", "fungible_tokens": [...], "non_fungible_tokens": [...] }

Parameters (stx_transfer_stx): recipient, amount_ustx, optional memo, dry_run.
Parameters (stx_transfer_sip10_ft): recipient, asset (e.g. SP...contract::token), amount, optional dry_run.
Parameters (stx_transfer_sip9_nft): recipient, asset, asset_id, optional dry_run.

Parameters (stx_call_contract): contract_address, contract_name, function_name, function_args (array of Clarity literals), optional dry_run.
Parameters (stx_deploy_contract): contract_name, clarity_code, optional dry_run.
Parameters (stx_read_contract): contract_address, contract_name, function_name, optional function_args.

Clarity argument examples: u100, i-5, true/false, none, 'SP... (principal), 0xDEADBEEF (buffer), "hello" (string-ascii).

Parameters (stx_sign_message): message.
Parameters (stx_sign_structured_message): domain, message (JSON string).
Parameters (stx_get_nonce): optional address.

Swaps, DeFi & bridge

Swap protocols: Alex, Bitflow, and Velar. Use protocol for quotes and pair listing: alex (pools and token prices), bitflow (ticker API), velar (Alex token prices). Execution: swap_execute supports protocol=alex only (default). For bitflow or velar you get a quote only; to execute, use protocol alex. Execution for Bitflow and Velar could be added via protocol SDKs (e.g. Velar’s @velarprotocol/velar-sdk returns contract-call params; Bitflow requires their SDK or API).

Parameters (swap_get_quote): token_in, token_out, amount, optional protocol (alex | bitflow | velar, default alex).
Parameters (swap_execute): token_in, token_out, amount, optional min_output, protocol (must be alex for execution), dry_run.
Parameters (sbtc_bridge_deposit): amount_sats, optional dry_run.
Parameters (sbtc_bridge_withdraw): amount_sats, btc_address, optional dry_run.
Parameters (stx_stack): amount_ustx, pox_address, num_cycles, optional dry_run.

BNS & market data

Parameters (bns_lookup): name (e.g. alice.btc).
Parameters (bns_get_names): address.
Parameters (bns_register): name, namespace (e.g. btc), optional dry_run.
Parameters (market_get_prices): coins (e.g. ["bitcoin", "blockstack"]).
Parameters (market_get_history): coin, days, optional interval (e.g. daily).
Parameters (portfolio_get_collectibles): optional limit.

Ledger hardware wallet (Stacks)

Requires a Ledger device connected via USB with the Stacks app open. Use interface: "tcp" for Speculos.

Parameters (ledger_get_stx_addresses): optional account, display, interface.
Parameters (ledger_sign_stx_transaction): tx_hex, optional derivation_path, interface.

Enhanced transaction queries

Advanced Stacks transaction queries with filtering, contract-specific queries, and mempool inclusion. Uses Hiro /extended/v2/addresses/ and /extended/v1/address/ endpoints.

Parameters (stx_query_transactions): optional address, limit, offset, tx_type (token_transfer, contract_call, smart_contract, coinbase, poison_microblock), unanchored (include mempool).
Parameters (stx_query_transactions_by_contract): contract_id (required), optional function_name, limit, offset.

Example response (stx_query_transactions): { "success": true, "address": "SP...", "transactions": [{ "txid": "0x...", "tx_type": "token_transfer", "status": "success", "block_height": 150000 }], "total": 42, "tx_type_filter": null, "unanchored": false }

Mempool operations

Monitor pending Stacks transactions, view mempool statistics, and track dropped transactions. Uses Hiro /extended/v1/tx/mempool/ endpoints.

Parameters (stx_mempool_list_pending): optional address, limit, offset.
Parameters (stx_mempool_get_dropped): optional limit, offset.

Example response (stx_mempool_get_stats): { "success": true, "tx_type_counts": { "token_transfer": 42, "contract_call": 18 }, "tx_simple_fee_averages": { "token_transfer": { "p50": 200 } } }

Block explorer

Query Stacks blocks by height, hash, or Bitcoin block association. Uses Hiro /extended/v2/blocks/ and /extended/v2/burn-blocks/ endpoints.

Parameters (stx_get_recent_blocks): optional limit, offset.
Parameters (stx_get_block_by_height): height (required).
Parameters (stx_get_block_by_hash): block_hash (required, with or without 0x prefix).
Parameters (stx_get_stacks_blocks_for_bitcoin_block): bitcoin_height (required), optional limit, offset.

Example response (stx_get_block_by_height): { "success": true, "height": 150000, "hash": "0x...", "burn_block_height": 935748, "tx_count": 12, "transaction_ids": ["0x..."] }

Contract event monitoring

Track events emitted by smart contracts and asset transfers for addresses. Uses Hiro /extended/v1/contract/ and /extended/v1/address/ endpoints.

Parameters (stx_get_contract_events): contract_id (required), optional limit, offset.
Parameters (stx_get_address_asset_events): optional address (default: wallet), limit, offset.

Example response (stx_get_contract_events): { "success": true, "contract_id": "SP...contract", "events": [{ "event_type": "fungible_token_asset", "tx_id": "0x...", "asset_id": "SP...::token", "amount": "1000" }], "total": 5 }

Token metadata

Query SIP-10 fungible and SIP-9 non-fungible token metadata and holder information. Uses Hiro Token Metadata API (/metadata/v1/).

Parameters (stx_get_token_metadata): contract_id (required), optional token_type (ft or nft, default: ft).
Parameters (stx_get_token_holders): contract_id (required), optional limit, offset.

Example response (stx_get_token_metadata): { "success": true, "contract_id": "SP...::alex-token", "name": "Alex Token", "symbol": "ALEX", "decimals": 8, "total_supply": "1000000000000" }

Network statistics & health

Query Stacks network status, peer info, and chain tip details. Uses Hiro /v2/info and /extended/v1/status endpoints.

Parameters: None.

Example response (stx_get_network_info): { "success": true, "peer_version": 402653189, "burn_block_height": 935748, "stacks_tip_height": 150000, "server_version": "stacks-node 2.5.0" }

Security

• Secrets: MUST NOT be returned in tool responses (keys, mnemonics, passphrases).

• Destructive ops: Send, sign-and-broadcast, and deploy tools support dry_run. Keep BTC_DRY_RUN=true unless you intend to broadcast. Require explicit confirmation before dry_run=false.

• Preview first: Use preview/estimate tools before sending (e.g. btc_wallet_preview_transfer, btc_estimate_fee, stx_preview_transfer).

• Limits: Optional BTC_MAX_SEND_BTC and BTC_MAX_FEE_SATS cap amount and fees.

• Env: Keep .env out of version control and restrict permissions. Run script loads it from repo root.

Testing

Unit tests live under tests/unit/ and target MCP server behavior and wallet modules:

# From mcp/btc_wallet (this directory) or repo root
python -m pytest mcp/btc_wallet/tests/unit -v

Test modules include: test_bitcoin_wallet_mcp_server.py, test_stx_wallet_mcp_server.py, test_ord_wallet_mcp_server.py, test_defi_wallet_mcp_server.py, test_phase5ab_mcp_server.py, test_phase5d_mcp_server.py, test_ledger_wallet_mcp_server.py, test_hiro_integration_mcp_server.py. Ledger tests require a device or Speculos.

Troubleshooting

Reference

• MCP: Model Context Protocol. Protocol and tool contract used by this server.

• Foundation: markmhendrickson/foundation. Shared development processes and documentation conventions. After cloning, run git submodule update --init foundation if the foundation/ directory is empty.