bitcoin MCP server
Commit Nov 14, 2026Provides an AI client with read-only access to Bitcoin data including HD wallet derivation, address queries, UTXOs, and mempool analysis.
Also known as junxit/mcp-bitcoin
- Stars
- 1
- Tools
- 27
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is bitcoin MCP?
bitcoin provides an AI client with read-only access to Bitcoin data including HD wallet derivation, address queries, UTXOs, and mempool analysis. It exposes 27 tools, such as derive_addresses, derive_from_path, derive_xpub.
Summary generated from the project's README
About bitcoin MCP server
Developers and Bitcoin enthusiasts can use this server to provide AI clients with read-only access to blockchain data. It enables tasks such as HD wallet derivation, address and UTXO queries, transaction lookups, and mempool analysis. The server supports various networks including mainnet, testnet, signet, and regtest, and can connect to backends like Bitcoin Core, Electrum, mempool.space, or Esplora.
Users can set up the server to work with public APIs for quick access or connect it to a private node for increased privacy. For enhanced security, it supports routing all backend connections through a Tor proxy with a fail-closed mechanism. While it can perform derivation using seed phrases if the MCP_BITCOIN_ALLOW_MNEMONIC setting is enabled, it is designed to function as a watch-only tool using xpubs, ypubs, or zpubs to keep sensitive keys out of the language model context.
This tool is strictly for information retrieval and inspection. It does not have the capability to build, sign, or broadcast transactions.
What you can do with it
- 1Derive multiple Bitcoin addressesGenerate a list of addresses from an extended public key for a specific account.
- 2Analyze network congestionCheck current fee rates and the status of the mempool to estimate transaction costs.
- 3Inspect transaction detailsDecode a partially signed Bitcoin transaction to verify destinations and fees before signing.
- 4Monitor wallet balancesRetrieve confirmed and unconfirmed balances and unspent outputs for a specific address.
Written from the project's README. Every use case is checked against a quote from it.
bitcoin MCP tools 27
Detected from the READMEderive_addressesderive_from_pathderive_xpubderive_entropy_bip85generate_mnemonicvalidate_mnemonicdecode_wifget_address_from_pubkeyget_balanceget_utxosget_tx_historyget_transaction
Show all 27 toolsShow fewer tools
get_raw_transactionget_blockget_block_heightdecode_raw_transactiondecode_psbtvalidate_addressdecode_scriptestimate_feeget_recommended_feesget_fee_histogramget_mempool_infoget_mempool_entrypinglist_backendsconvert_units
Configuration
MCP_BITCOIN_ALLOW_MNEMONICMCP_BITCOIN_CORE_URLMCP_BITCOIN_ELECTRUM_URLMCP_BITCOIN_ESPLORA_URLMCP_BITCOIN_MEMPOOL_URLMCP_BITCOIN_NETWORKMCP_BITCOIN_PROVIDER_PRIORITYMCP_BITCOIN_TOR_PROXY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejunxit/mcp-bitcoin is public and reachablegithub.com/junxit/mcp-bitcoin ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/junxit/mcp-bitcoin ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model27 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-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.
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.
bitcoin MCP questions
What tools does bitcoin MCP provide?
It exposes 27 tools, including derive_addresses, derive_from_path, derive_xpub, derive_entropy_bip85, generate_mnemonic.
Is it safe to use my seed phrase with this server?
Using a seed phrase is risky because it is sent to the language model provider and saved in conversation history. It is recommended to use an xpub instead.
How can I use seed phrase tools if I want to?
You must explicitly enable them by setting the MCP_BITCOIN_ALLOW_MNEMONIC environment variable to true.