mcp-bitcoin
Provides read-only Bitcoin blockchain capabilities, including HD wallet derivation, address and UTXO queries, transaction lookup, fee estimation, mempool analysis, and PSBT inspection, with support for Bitcoin Core, Electrum, mempool.space, and Esplora backends across mainnet, testnet, signet, and regtest.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-bitcoin What's the current recommended fee rate for a fast Bitcoin transaction?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncConfirm it works:
uv run mcp-bitcoin --help 2>/dev/null || echo "installed"
uv run pytest -qConfigure
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 | ||
| offline | Addresses from an xpub or seed phrase |
| offline | One key at any BIP-32 path, all four formats |
| offline · 🔑 | Account xpub/ypub/zpub from a seed phrase |
| offline · 🔑 | BIP-85 child seed or entropy |
| offline · 🔑 | New BIP-39 phrase |
| offline | Check word count, wordlist and checksum |
| offline · 🔑 | Public key and addresses for a WIF key |
| offline | Hex public key to address |
🔑 = requires MCP_BITCOIN_ALLOW_MNEMONIC=true
Chain queries
Tool | ||
| backend | Confirmed and unconfirmed balance |
| backend | Unspent outputs, filterable by confirmations |
| backend | History, newest first, cursor-paginated |
| backend | Fetch and decode a transaction |
| backend | Raw hex |
| backend | Block header by hash or height |
| backend | Current chain tip |
| offline | Decode raw hex with destinations |
| offline | Decode a PSBT with destinations and fee |
| offline | Validity, type and network |
| offline | Script type and address |
Fees and mempool
Tool | ||
| backend | Rate for a confirmation target |
| backend | Economy / normal / priority |
| backend | Mempool fee distribution |
| backend | Size, vsize, minimum rate |
| backend | Details for an unconfirmed transaction |
Utility
Tool | ||
| Health and backend reachability | |
| Backends, status and capabilities | |
| offline | BTC / mBTC / bits / sats |
Configuration reference
Variable | Default | |
|
|
|
| — | Bitcoin Core RPC; omit credentials to use cookie auth |
| auto | Override the |
| — |
|
|
| Accept self-signed certs (unauthenticated) |
| — | mempool.space API base |
| — | Esplora API base |
|
| Failover order |
| — | SOCKS5 proxy; fail-closed when set |
|
| Enable seed-phrase and private-key tools |
|
| Per-backend request timeout, seconds |
|
| 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 toolsconvert_unitsARead-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_psbtARead-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_transactionARead-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_scriptARead-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_wifARead-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_addressesARead-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_bip85ARead-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_pathARead-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_xpubARead-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_feeARead-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_mnemonicARead-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_pubkeyARead-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_balanceARead-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_blockARead-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_heightARead-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_histogramCRead-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_entryARead-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_infoARead-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_transactionBRead-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_recommended_feesARead-only
Get economy, normal and priority fee rates. Needs a backend.
Args: network: Override the server's network for this call.
Inputs: network. Returns: result
get_transactionARead-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_historyARead-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_utxosARead-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_backendsARead-only
List configured backends, their reachability and their capabilities.
Inputs: no named parameters. Returns: result
pingARead-only
Check server health and which backends are reachable.
Start here when other tools report backend errors.
Inputs: no named parameters. Returns: result
validate_addressARead-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_mnemonicARead-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
Scored across 27 tools
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.
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.
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.
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
Read-only Bitcoin blockchain, mempool, mining, market, and on-chain analytics; no API key.
Read-only THORChain swap quotes, liquidity pools, and network status.
Read-only BlockReq docs, EVM JSON-RPC, and on-chain DEX and wallet data
Read-only market and on-chain data for Bitcoin, Ethereum and more; on-chain from our own nodes.
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides 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.721 npm4MIT
- AlicenseNot gradedqualityFmaintenanceEnables 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.25Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables querying Bitcoin blockchain data including blocks, transactions, addresses, mempool, and fee estimates via the Blockstream.info Esplora API.110 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables querying public Bitcoin network data including fees, mempool status, hashrate, transactions, address stats, and Lightning network information without requiring API keys.MIT