Bitcoin Core integration through the Model Context Protocol
Bitcoin MCP presents 25 tools with READ_ONLY risk classification, all registered via FastMCP decorators. Tool names follow verb_noun convention (get_*, analyze_*) and are generally clear. However, critical gaps emerge in schema completeness, parameter documentation, and output structure definition. Most tools lack explicit input parameter descriptions in the JSON Schema visible in code; descriptions exist in docstrings but are not validated against actual schema registration. Output schemas are entirely undocumented, no tool declares what fields the JSON response contains, preventing LLMs from chaining calls or extracting specific data. Error handling is minimal: most tools catch exceptions and return free-text error strings, providing no actionable recovery guidance. The Bitfeed tool's description is unusually detailed but still lacks schema clarity. Tool descriptions range from adequate (100-200 chars) to verbose (300+ chars), but parameter descriptions within schemas are sparse or missing entirely. This pattern is typical of STDIO-only servers that prioritize functionality over agent-readiness.
Analyze a transaction with detailed information including inputs, outputs, fee calculation, and transaction metadata.
Decode a raw transaction hex string into a readable transaction object.
Estimate the fee rate needed for a transaction to confirm within a target number of blocks.
Get accurate 3D coordinates (x, y, z) and sizes (width, height, depth) of parcels from a BTC block based on Bitfeed representation. Units are in meters. Do not modify the individuall numbers because it breaks the accuracy of the visual representation as a whole. For any sizing or scaling adjustments, use the "scale" parameter (default: 0.5 meter). Returns a JSON object with details about the specific Block including: parcels: array of 3D representations of transactions in 3D sizes and coordinates, totalWidth: the final width of the visual representation (in meters), parcelColor: hex color code, blockNumber: the block height number, totalParcels: total transactions
Get block data for a specific block hash. Parameters: - blockhash: The hash of the block to get - verbosity: The verbosity level (0-2, default=1) 0: Returns a hex-encoded string of the block 1: Returns an object with block header and transaction IDs 2: Returns an object with block header and complete transaction objects Returns block data based on the specified verbosity level.
NO OUTPUT SCHEMAS DOCUMENTED. All 25 tools return JSON strings (via json.dumps) but provide zero documentation of response structure. LLMs cannot extract specific fields, cannot chain calls, and cannot validate if they received expected data. E.g., get_blockchain_info returns a JSON object but no schema specifies whether it includes 'chain', 'blocks', 'difficulty', etc., forcing LLMs to guess or re-prompt.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | D | 53 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 48 | - | v1 |
Get the block hash for a specific block height. Parameters: - height: Block height to get the hash for. Block height only increases as more blocks are mined. Returns the block hash as a hex string.
Get computed statistics for a specific block. Parameters: - hash_or_height: Block hash or height to get statistics for Returns computed statistics about the specified block including averages for feerate, txsize, and other metrics.
Get information about the current state of the blockchain and network. Returns a JSON object with details about the current blockchain state including: chain, blocks, headers, bestblockhash, difficulty, mediantime, verificationprogress, pruned (if applicable), and other blockchain metrics.
Get a comprehensive status report about the blockchain including network info, mempool status, and fee estimates.
Get information about all known chain tips in the node, including the main chain and any orphaned branches. Returns information about all known tips in the block tree, including the main chain and orphaned branches.
Get statistics about chain transaction volume. Parameters: - nblocks: Number of blocks to include in the stats (default: 30) - blockhash: The hash of the block that ends the window (default: chain tip) Returns statistics about chain transaction volume and rates.
Get detailed information about a specific block including header, transactions, and computed statistics.
Get the current difficulty of the Bitcoin network. Returns the current proof-of-work difficulty as a multiple of the minimum difficulty.
Get the difficulty history over a number of difficulty adjustment periods with analysis of changes and time deviations.
Get the fee history over a number of recent blocks with statistics and analysis.
Estimate the network hashrate based on recent blocks.
Get mempool ancestors for a transaction.
Get mempool descendants for a transaction.
Get detailed mempool entry information for a transaction.
Get information about the node's current transaction memory pool. Returns details about the memory pool including size, memory usage, and fee statistics.
Get all transactions currently in the memory pool.
Get information about the Bitcoin network including version, protocol version, connection count, and network configuration.
Get raw transaction data by transaction ID. Can return either hex-encoded data or decoded transaction object depending on verbosity parameter.
Get details about an unspent transaction output (UTXO). Parameters: - txid: The transaction id - n: The output number (vout) - include_mempool: Whether to include the mempool (default: true) Returns details about the specified unspent transaction output, if it exists in the UTXO set.
Get statistics about the unspent transaction output (UTXO) set. Returns statistics about the UTXO set including total amount, number of transactions, and disk size usage.
SPARSE PARAMETER DESCRIPTIONS IN SCHEMAS. While tool docstrings contain parameter descriptions, the actual JSON Schema input definitions show minimal inline description text. E.g., get_tx_out has 'txid' and 'n' parameters with descriptions like 'The transaction id' and 'The output number (vout)' in the source spec, but only the broadest description is visible. Many parameters lack detail about expected format, valid ranges, or dependencies. This forces LLMs to infer intent from names alone.
MINIMAL ERROR HANDLING & NO RECOVERY GUIDANCE. All tools wrap exceptions in try-catch and return free-text error strings (e.g., 'Error getting blockchain info: ...'). No tool distinguishes retryable errors from user-fixable ones. No tool returns actionable guidance (e.g., 'Connection to Bitcoin Core failed. Ensure bitcoin-cli is installed and bitcoin-coind is running on the configured RPC port'). Stack traces are logged but not included in responses, leaving LLMs with no path forward.
MISSING PARAMETER VALIDATION & CONSTRAINT DOCUMENTATION. Several tools accept numeric or string parameters without documented constraints. E.g., get_bitfeed_3d_representation accepts 'scale' as a float with no min/max; get_chain_tx_stats accepts 'nblocks' as an integer with no upper bound; estimate_smart_fee accepts 'conf_target' with no documented valid range. LLMs can pass absurd values (scale=-100, nblocks=999999) that break Bitcoin RPC calls or cause timeouts.
INCONSISTENT PARAMETER NAMING FOR BLOCK IDENTIFIERS. Tools use 'blockhash' (get_block), 'hash_or_height' (get_block_stats), 'block_identifier' (get_detailed_block_info), and plain 'blockHeight' (get_bitfeed_3d_representation). This forces LLMs to reason about parameter name mappings rather than composing tools intuitively. A canonical 'block_identifier' or two explicit 'block_hash' + 'block_height' params would reduce confusion.
TOOL DESCRIPTIONS EXCEED RECOMMENDED LENGTH. Several tools have verbose descriptions (300+ characters), which waste tokens and bury key details. E.g., get_bitfeed_3d_representation's description is ~380 chars; get_block's is ~250 chars. Recommendation: keep descriptions between 10-200 chars, with output schema documented separately.
NO PAGINATION OR RESULT LIMITING. Tools like get_mempool_transactions and get_chain_tips do not document whether they cap results or support pagination (offset/limit/cursor). If a mempool contains 10,000 transactions, returning all at once would blow the context window. No tool accepts limit or offset parameters.
MISSING TOOL ANNOTATIONS FOR LLM GUIDANCE. No tools declare readOnlyHint, destructiveHint, or idempotentHint annotations. While all 25 tools are marked READ_ONLY, explicit tool annotations would let LLMs immediately understand safe/unsafe operations without parsing descriptions. FastMCP supports these via @mcp.tool(...) decorators.