Skip to main content
Glama
mcp-bitcoin

mcp-bitcoin

by junxit

mcp-bitcoin

An MCP server that gives Claude — or any MCP-compatible client — a read-only window into Bitcoin: HD wallet derivation, address and UTXO queries, transaction lookup, fee estimation and mempool analysis, against your own node or public APIs, over Tor if you want it.

Status: pre-alpha (v0.1.0). The derivation engine is verified against the published BIP test vectors and the query layer has been exercised against live APIs. It has not seen broad real-world use. Treat results as informational and cross-check anything that matters.


⚠️ Read this before you use a seed phrase

Anything you pass to an MCP tool goes into a language model's context.

If you paste a seed phrase into a tool call, that phrase is transmitted to whatever inference provider your client uses — for a hosted client, a third-party API over the network — and written into your client's saved conversation history. It may be cached or retained in logs you do not control.

No amount of care inside this server can undo that. It is a property of putting a secret in a prompt.

So this server is watch-only by default. Every tool that accepts a seed phrase or private key refuses to run unless you explicitly set MCP_BITCOIN_ALLOW_MNEMONIC=true.

You almost certainly don't need to. Derive an account xpub once on a machine that isn't running this server, then pass that instead — every address, balance, UTXO and history feature works watch-only:

derive_addresses(source="zpub6rFR7y4Q2Aij...", count=20)

If you do enable seed-phrase tools, use a testnet or throwaway seed. See SECURITY.md.


Related MCP server: Maestro MCP Server

What it does

Derivation

BIP-32/39/44/49/84/86/85 — Legacy, Nested SegWit, Native SegWit and Taproot, verified against the spec vectors

Watch-only

Full address/balance/UTXO/history from an xpub, ypub or zpub

Chain queries

Balances, UTXOs, paginated history, transactions, blocks, scripts

Fees & mempool

Smart estimates, recommended tiers, fee histogram, mempool stats

PSBT inspection

Decode a PSBT with destinations, fee and warnings before you sign elsewhere

Backends

Bitcoin Core, Electrum, mempool.space, Esplora — with priority failover

Networks

mainnet, testnet, signet, regtest

Privacy

Optional Tor routing, enforced fail-closed

It cannot build, sign or broadcast transactions. That is deliberate — see ROADMAP.md for why, and what replaces it.


Install

Not yet on PyPI. Install from source:

git clone https://github.com/junxit/mcp-bitcoin
cd mcp-bitcoin
uv sync

Confirm it works:

uv run mcp-bitcoin --help 2>/dev/null || echo "installed"
uv run pytest -q

Configure

Add a block to your MCP client config. For Claude Desktop that is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS; for Claude Code, .mcp.json in your project or ~/.claude.json.

Replace /ABSOLUTE/PATH/TO/mcp-bitcoin with where you cloned it.

Public APIs — no node required

The quickest way to start. Uses mempool.space with Blockstream as a fallback.

{
  "mcpServers": {
    "bitcoin": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/mcp-bitcoin", "mcp-bitcoin"],
      "env": {
        "MCP_BITCOIN_NETWORK": "mainnet",
        "MCP_BITCOIN_MEMPOOL_URL": "https://mempool.space/api",
        "MCP_BITCOIN_ESPLORA_URL": "https://blockstream.info/api",
        "MCP_BITCOIN_PROVIDER_PRIORITY": "mempool,esplora"
      }
    }
  }
}

Public APIs see every address you look up. If that matters, self-host or use Tor.

Testnet

{
  "mcpServers": {
    "bitcoin-testnet": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/mcp-bitcoin", "mcp-bitcoin"],
      "env": {
        "MCP_BITCOIN_NETWORK": "testnet",
        "MCP_BITCOIN_MEMPOOL_URL": "https://mempool.space/testnet4/api",
        "MCP_BITCOIN_ESPLORA_URL": "https://blockstream.info/testnet/api",
        "MCP_BITCOIN_PROVIDER_PRIORITY": "mempool,esplora",
        "MCP_BITCOIN_ALLOW_MNEMONIC": "true"
      }
    }
  }
}

Enabling seed-phrase tools is reasonable here — testnet coins are worthless.

Your own Bitcoin Core

Omit credentials from the URL and the server reads ~/.bitcoin/.cookie.

{
  "mcpServers": {
    "bitcoin": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/mcp-bitcoin", "mcp-bitcoin"],
      "env": {
        "MCP_BITCOIN_CORE_URL": "http://127.0.0.1:8332",
        "MCP_BITCOIN_ELECTRUM_URL": "ssl://192.168.1.50:50002",
        "MCP_BITCOIN_PROVIDER_PRIORITY": "core,electrum"
      }
    }
  }
}

Core has no address index, so pair it with Electrum, mempool.space or Esplora for get_balance, get_utxos and get_tx_history. The server routes each call to a backend that supports it.

Self-hosted over Tor

{
  "mcpServers": {
    "bitcoin": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/mcp-bitcoin", "mcp-bitcoin"],
      "env": {
        "MCP_BITCOIN_TOR_PROXY": "socks5://127.0.0.1:9050",
        "MCP_BITCOIN_CORE_URL": "http://yournode.onion:8332",
        "MCP_BITCOIN_ELECTRUM_URL": "ssl://yourelectrum.onion:50002",
        "MCP_BITCOIN_MEMPOOL_URL": "http://yourmempool.onion/api",
        "MCP_BITCOIN_PROVIDER_PRIORITY": "core,electrum,mempool"
      }
    }
  }
}

With MCP_BITCOIN_TOR_PROXY set, every backend connection routes through the proxy and the server refuses to start if it is unreachable. socks5h:// is accepted and normalized. Certificate verification is skipped for .onion hosts because the onion address already authenticates the endpoint.

Public mempool.space over Tor

{
  "mcpServers": {
    "bitcoin": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/mcp-bitcoin", "mcp-bitcoin"],
      "env": {
        "MCP_BITCOIN_TOR_PROXY": "socks5://127.0.0.1:9050",
        "MCP_BITCOIN_MEMPOOL_URL": "http://mempoolhqx4isw62xs7abwphsq7ldayuidyx2v2oethdhhj6mlo2r6ad.onion/api",
        "MCP_BITCOIN_PROVIDER_PRIORITY": "mempool"
      }
    }
  }
}

Regtest

{
  "mcpServers": {
    "bitcoin-regtest": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/mcp-bitcoin", "mcp-bitcoin"],
      "env": {
        "MCP_BITCOIN_NETWORK": "regtest",
        "MCP_BITCOIN_CORE_URL": "http://127.0.0.1:18443",
        "MCP_BITCOIN_PROVIDER_PRIORITY": "core",
        "MCP_BITCOIN_ALLOW_MNEMONIC": "true"
      }
    }
  }
}

Start the node with bitcoind -regtest -fallbackfee=0.0001. Derived addresses correctly use the bcrt1 prefix.


Example session

You:  What's the current Bitcoin fee rate, and how busy is the mempool?

Claude: [get_recommended_fees] [get_mempool_info]
        Fees are low right now — economy and normal are both 1 sat/vB,
        priority is 3. The mempool holds 82,735 transactions (41.6 MvB),
        so there's no meaningful backlog. A 1-2 sat/vB transaction should
        confirm within a few blocks.

You:  Show me the first 3 addresses for this account key: zpub6rFR7y4Q2Aij...

Claude: [derive_addresses]
        m/84'/0'/0'/0/0  bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu
        m/84'/0'/0'/0/1  bc1qnjg0jd8228aq7egyzacy8cys3knf9xvrerkf9g
        m/84'/0'/0'/0/2  bc1qp59yckz4ae5c4efgw2s5wfyvrz0ala7rgvuz8z

You:  Any balance on the first one?

Claude: [get_balance] [get_utxos]
        0.00000000 BTC — no UTXOs, and no transaction history.

Tools

Tools marked offline work with no backend configured.

Derivation

Tool

derive_addresses

offline

Addresses from an xpub or seed phrase

derive_from_path

offline

One key at any BIP-32 path, all four formats

derive_xpub

offline · 🔑

Account xpub/ypub/zpub from a seed phrase

derive_entropy_bip85

offline · 🔑

BIP-85 child seed or entropy

generate_mnemonic

offline · 🔑

New BIP-39 phrase

validate_mnemonic

offline

Check word count, wordlist and checksum

decode_wif

offline · 🔑

Public key and addresses for a WIF key

get_address_from_pubkey

offline

Hex public key to address

🔑 = requires MCP_BITCOIN_ALLOW_MNEMONIC=true

Chain queries

Tool

get_balance

backend

Confirmed and unconfirmed balance

get_utxos

backend

Unspent outputs, filterable by confirmations

get_tx_history

backend

History, newest first, cursor-paginated

get_transaction

backend

Fetch and decode a transaction

get_raw_transaction

backend

Raw hex

get_block

backend

Block header by hash or height

get_block_height

backend

Current chain tip

decode_raw_transaction

offline

Decode raw hex with destinations

decode_psbt

offline

Decode a PSBT with destinations and fee

validate_address

offline

Validity, type and network

decode_script

offline

Script type and address

Fees and mempool

Tool

estimate_fee

backend

Rate for a confirmation target

get_recommended_fees

backend

Economy / normal / priority

get_fee_histogram

backend

Mempool fee distribution

get_mempool_info

backend

Size, vsize, minimum rate

get_mempool_entry

backend

Details for an unconfirmed transaction

Utility

Tool

ping

Health and backend reachability

list_backends

Backends, status and capabilities

convert_units

offline

BTC / mBTC / bits / sats


Configuration reference

Variable

Default

MCP_BITCOIN_NETWORK

mainnet

mainnet, testnet, signet, regtest

MCP_BITCOIN_CORE_URL

—

Bitcoin Core RPC; omit credentials to use cookie auth

MCP_BITCOIN_CORE_COOKIE_PATH

auto

Override the .cookie location

MCP_BITCOIN_ELECTRUM_URL

—

ssl://host:50002 or tcp://host:50001

MCP_BITCOIN_ELECTRUM_ALLOW_SELF_SIGNED

false

Accept self-signed certs (unauthenticated)

MCP_BITCOIN_MEMPOOL_URL

—

mempool.space API base

MCP_BITCOIN_ESPLORA_URL

—

Esplora API base

MCP_BITCOIN_PROVIDER_PRIORITY

core,electrum,mempool,esplora

Failover order

MCP_BITCOIN_TOR_PROXY

—

SOCKS5 proxy; fail-closed when set

MCP_BITCOIN_ALLOW_MNEMONIC

false

Enable seed-phrase and private-key tools

MCP_BITCOIN_TIMEOUT

30

Per-backend request timeout, seconds

MCP_BITCOIN_FAILOVER_COOLDOWN

60

Initial backoff for a failed backend, seconds


Troubleshooting

"No backend is configured" — set at least one *_URL variable. Derivation, validation and decoding still work without one.

"Cannot run 'get_balance' … does not support this operation" — Bitcoin Core has no address index. Add an Electrum, mempool.space or Esplora backend.

Backend errors — run ping for per-backend reachability and latency, and list_backends to see which capabilities each one provides.

"Address … is a mainnet address, but this server is configured for testnet" — working as intended. Querying across networks returns another chain's data, which looks like missing funds. Change MCP_BITCOIN_NETWORK or use the right address.

Electrum TLS failures — many Electrum servers use self-signed certificates. For a server you trust, set MCP_BITCOIN_ELECTRUM_ALLOW_SELF_SIGNED=true, and read the caveat in SECURITY.md.

Server won't start with Tor enabled — that is the fail-closed guarantee. Start Tor, or unset MCP_BITCOIN_TOR_PROXY.


Development

uv sync --all-groups
uv run pytest
uv run ruff check . && uv run mypy src/

See CONTRIBUTING.md. The short version: assert against published spec vectors, not against this implementation.


License

Apache-2.0 © 2026 Jade Naaman.

Provided without warranty. You are responsible for verifying anything this tool tells you before acting on it.

Available Tools

27 tools
convert_unitsA
Read-only

Convert between Bitcoin units. Works offline.

Args: amount: Amount to convert, e.g. "0.001". from_unit: Source unit: btc, mbtc, bit or sat. to_unit: Target unit: btc, mbtc, bit or sat.

Inputs: amount (required), to_unit (required), from_unit (required). Returns: result

decode_psbtA
Read-only

Decode a PSBT, showing every destination, the fee and signing status.

Works offline. Use this to check where funds are going before signing in your wallet. This server cannot sign or broadcast.

Args: psbt: The base64-encoded PSBT. network: Override the server's network for address rendering.

Inputs: psbt (required), network. Returns: result

decode_raw_transactionA
Read-only

Decode raw transaction hex, showing destinations. Works offline.

Args: raw_tx: The raw transaction hex. network: Override the server's network for address rendering.

Inputs: raw_tx (required), network. Returns: result

decode_scriptA
Read-only

Decode a scriptPubKey to its type and address. Works offline.

Args: script_hex: The hex-encoded script. network: Override the server's network for address rendering.

Inputs: script_hex (required), network. Returns: result

decode_wifA
Read-only

Show the public key and addresses for a WIF private key. Works offline.

Requires MCP_BITCOIN_ALLOW_MNEMONIC=true. The private key is not echoed back.

Args: wif: The WIF-encoded private key. network: Override the server's network for this call.

Inputs: wif (required), network. Returns: result

derive_addressesA
Read-only

Derive addresses from an xpub (preferred) or a seed phrase. Works offline.

Passing an xpub/ypub/zpub is the safe path and needs no special permission. Passing a mnemonic requires MCP_BITCOIN_ALLOW_MNEMONIC=true.

Args: source: An xpub/ypub/zpub, or a BIP-39 mnemonic. passphrase: Optional BIP-39 passphrase; only used with a mnemonic. address_type: legacy, nested_segwit, native_segwit or taproot. account: BIP-44 account index. change: 0 for receiving addresses, 1 for change. start_index: First address index. count: How many addresses to derive, up to 500. network: Override the server's network for this call.

Inputs: source (required), count, change, account, +4 more. Returns: result

derive_entropy_bip85A
Read-only

Derive a deterministic child seed or entropy from a master seed (BIP-85).

Works offline. Requires MCP_BITCOIN_ALLOW_MNEMONIC=true.

Args: mnemonic: The master BIP-39 seed phrase. index: Derivation index; each index gives a different child. passphrase: Optional BIP-39 passphrase for the master seed. child_mnemonic_words: Set to 12/15/18/21/24 to derive a child seed phrase. Leave unset to derive raw hex entropy instead. num_bytes: Entropy length, 16-64, when deriving raw entropy.

Inputs: mnemonic (required), index, num_bytes, passphrase, +1 more. Returns: result

derive_from_pathA
Read-only

Derive one key at an arbitrary BIP-32 path, in every address format.

Works offline. Private keys are never returned.

Args: source: An xpub/ypub/zpub, or a BIP-39 mnemonic. path: A BIP-32 path such as "m/84'/0'/0'/0/0". passphrase: Optional BIP-39 passphrase; only used with a mnemonic. network: Override the server's network for this call.

Inputs: path (required), source (required), network, passphrase. Returns: result

derive_xpubA
Read-only

Extract an account xpub/ypub/zpub from a seed phrase. Works offline.

Requires MCP_BITCOIN_ALLOW_MNEMONIC=true. Run this once, keep the xpub, and every later address query can stay watch-only.

Args: mnemonic: The BIP-39 seed phrase. standard: bip44, bip49, bip84 or bip86. passphrase: Optional BIP-39 passphrase. account: Account index. network: Override the server's network for this call.

Inputs: mnemonic (required), account, network, standard, +1 more. Returns: result

estimate_feeA
Read-only

Estimate the fee rate to confirm within a number of blocks. Needs a backend.

Args: target_blocks: Desired confirmation target, 1 to 1008. network: Override the server's network for this call.

Inputs: network, target_blocks. Returns: result

generate_mnemonicA
Read-only

Generate a new BIP-39 seed phrase. Works offline.

Requires MCP_BITCOIN_ALLOW_MNEMONIC=true, because the generated phrase is returned into the conversation and therefore into your client's transcript. Never use a phrase generated this way for real funds — use a hardware wallet or an offline generator.

Args: word_count: 12, 15, 18, 21 or 24. Defaults to 24.

Inputs: word_count. Returns: result

get_address_from_pubkeyA
Read-only

Convert a hex public key to an address. Works offline.

Args: pubkey: Hex-encoded public key, compressed or uncompressed. address_type: legacy, nested_segwit, native_segwit, taproot, or "all". network: Override the server's network for this call.

Inputs: pubkey (required), network, address_type. Returns: result

get_balanceA
Read-only

Get an address's confirmed and unconfirmed balance. Needs a backend.

Args: address: The Bitcoin address to look up. network: Override the server's network for this call.

Inputs: address (required), network. Returns: result

get_blockA
Read-only

Fetch a block header by hash or height. Needs a backend.

Args: block: A block hash, or a block height as a number. network: Override the server's network for this call.

Inputs: block (required), network. Returns: result

get_block_heightA
Read-only

Get the current chain tip height. Needs a backend.

Args: network: Override the server's network for this call.

Inputs: network. Returns: result

get_fee_histogramC
Read-only

Get the mempool fee distribution. Needs a backend.

Args: network: Override the server's network for this call.

Inputs: network. Returns: result

get_mempool_entryA
Read-only

Get mempool details for an unconfirmed transaction. Needs a backend.

Args: txid: The 64-hex-character transaction ID. network: Override the server's network for this call.

Inputs: txid (required), network. Returns: result

get_mempool_infoA
Read-only

Get mempool size, vsize and minimum fee rate. Needs a backend.

Args: network: Override the server's network for this call.

Inputs: network. Returns: result

get_raw_transactionB
Read-only

Fetch a transaction's raw hex. Needs a backend.

Args: txid: The 64-hex-character transaction ID. network: Override the server's network for this call.

Inputs: txid (required), network. Returns: result

get_transactionA
Read-only

Fetch and decode a transaction by txid. Needs a backend.

Args: txid: The 64-hex-character transaction ID. network: Override the server's network for this call.

Inputs: txid (required), network. Returns: result

get_tx_historyA
Read-only

Get an address's transaction history, newest first. Needs a backend.

Paginates by cursor: pass the returned next_cursor as after_txid to page on.

Args: address: The Bitcoin address to look up. limit: How many transactions to return, up to 100. after_txid: Continue after this txid, from a previous next_cursor. network: Override the server's network for this call.

Inputs: address (required), limit, network, after_txid. Returns: result

get_utxosA
Read-only

List an address's unspent outputs. Needs a backend.

Args: address: The Bitcoin address to look up. min_confirmations: Exclude UTXOs below this confirmation count. network: Override the server's network for this call.

Inputs: address (required), network, min_confirmations. Returns: result

list_backendsA
Read-only

List configured backends, their reachability and their capabilities.

Inputs: no named parameters. Returns: result

pingA
Read-only

Check server health and which backends are reachable.

Start here when other tools report backend errors.

Inputs: no named parameters. Returns: result

validate_addressA
Read-only

Check whether an address is valid and which network it belongs to.

Works offline.

Args: address: The address to check. network: Compare against this network instead of the server default.

Inputs: address (required), network. Returns: result

validate_mnemonicA
Read-only

Check a BIP-39 phrase's word count, wordlist and checksum. Works offline.

Args: mnemonic: The space-separated seed phrase to check.

Inputs: mnemonic (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools target a distinct resource/action, and the descriptions clearly specify inputs and outputs. A few pairs such as get_transaction/get_raw_transaction/decode_raw_transaction and estimate_fee/get_recommended_fees are close enough that an agent could pick the wrong one without reading carefully.

    Naming Consistency4/5

    The vast majority follow a clean snake_case verb_noun pattern: get_*, decode_*, derive_*, and validate_* are consistent. The pattern is only slightly interrupted by bare ping and list_backends, and by a minor mix of list_ vs get_ for similar lookup operations.

    Tool Count3/5

    27 tools is on the heavy side for a single server, even for a broad Bitcoin domain; the health tools and the fee/mempool cluster could plausibly be consolidated. Each tool has a distinguishable purpose, so the count feels borderline rather than chaotic.

    Completeness4/5

    The server covers mnemonic handling, key derivation, address/script/PSBT decoding, balances, UTXOs, history, transactions, blocks, fees, and mempool state—strong coverage for a read-only Bitcoin utility. The main gaps are transaction building/broadcasting and block-transaction listing, though the server explicitly positions itself as non-signing and non-broadcasting.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Provides real-time Bitcoin blockchain data by querying the mempool.space API, offering tools to get address statistics, transaction history, UTXOs, transaction details, and block information.
      7
      21 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables interaction with the Bitcoin blockchain through the Maestro API platform. Provides tools for exploring blocks, transactions, addresses, mempool monitoring, market prices, wallet operations, and node RPC calls on Bitcoin mainnet and testnet4.
      25
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying Bitcoin blockchain data including blocks, transactions, addresses, mempool, and fee estimates via the Blockstream.info Esplora API.
      110 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying public Bitcoin network data including fees, mempool status, hashrate, transactions, address stats, and Lightning network information without requiring API keys.
      MIT