Content
# bitcoin-mcp
bitcoin-mcp extends AI utilities with accurate Bitcoin blockchain data based on [MCP](https://modelcontextprotocol.io/). bitcoin-mcp is a streamlined Model Context Protocol (MCP) server implementation that interfaces with Bitcoin Core (full-node) through `bitcoin-cli`. This bitcoin-mcp server provides Claude Desktop (or other mcp clients) with READ access to Bitcoin blockchain data **WITHOUT wallet functionality**.
## Features
AI agent meets the most secure data ledger - Bitcoin.
- Query real-time Bitcoin blockchain information (via `bitcoin-cli`, but WITHOUT any wallet calls)
- Access mempool, blocks, and transaction data
- Generate custom 3D visualization of BTC blocks based on TX output values and BitFeed representation (i.e., those beautiful rectangles on [mempool.space](https://mempool.space/))
## Prerequisites
- Claude Desktop (or other mcp clients)
- Python 3.10+
- **Bitcoin full-node** (w. `bitcoin-cli`)
- (Windows)
## Installation
1. Clone the repo to your up-to-date btc full node machine (required for bitcoin-mcp to work)
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Make sure Bitcoin Core is up-to-date and running. Configure `.env` and add `BITCOIN_CLI_PATH` so that MCP server can find `bitcoin-cli`
- Have this line `BITCOIN_CLI_PATH=C:\\Program Files\\Bitcoin\\daemon\\bitcoin-cli` in `.env`
4. Claude Desktop Configuration (standard setup for any mcp servers)
- update `path\\to\\` to your local `bitcoin-mcp` folder
```
{
"mcpServers": {
"bitcoin-mcp": {
"command": "python",
"args": ["path\\to\\bitcoin-mcp\\bitcoin_mcp_server.py"],
"env": {}
}
}
}
```
## Test the server:
You can test the python server to see if it loads your btc full node.
```bash
python bitcoin_mcp_server.py
```
## Available Tools
Mainly for mcp clients like Claude Desktop to utilize Bitcoin blockchain info, so NO WALLET FUNCTIONS ARE INCLUDED.
### Blockchain Information
| Tool | Description |
|------|-------------|
| `get_blockchain_info` | Get current blockchain state |
| `get_block_hash` | Get block hash for a specific height |
| `get_block` | Get block data by hash |
| `get_block_stats` | Get block statistics |
| `get_chain_tips` | Get information about chain tips |
| `get_chain_tx_stats` | Get chain transaction statistics |
| `get_difficulty` | Get current difficulty |
| `get_network_info` | Get network information |
| `get_blockchain_status` | Get comprehensive blockchain status |
| `get_detailed_block_info` | Get detailed block information |
| `search_blocks` | Search for blocks meeting criteria |
| `get_bitfeed_3d_representation` | Get 3D representation of a BTC block based on TX data |
### Transaction Information
| Tool | Description |
|------|-------------|
| `get_mempool_info` | Get mempool information |
| `get_tx_out` | Get UTXO information |
| `get_tx_out_set_info` | Get UTXO set statistics |
| `get_raw_transaction` | Get raw transaction data |
| `decode_raw_transaction` | Decode raw transaction |
| `estimate_smart_fee` | Estimate transaction fee |
| `analyze_transaction` | Analyze transaction details |
### Analytics
| Tool | Description |
|------|-------------|
| `get_difficulty_history` | Get difficulty adjustment history |
| `get_fee_history` | Get transaction fee history |
| `get_hashrate_estimate` | Estimate network hashrate |
| `get_block_time_distribution` | Analyze block time distribution |
| `analyze_blockchain` | Comprehensive blockchain analysis |
### Configuration
| Tool | Description |
|------|-------------|
| `configure_bitcoin_cli` | Configure bitcoin-cli settings |
| `get_config_info` | Get current server configuration |
| `update_server_config` | Update server configuration |
## Code Structure
- `bitcoin_mcp_server.py`: Main server entry point
- `bitcoin_connection.py`: Bitcoin Core connection utilities
- `bitcoin_config.py`: Configuration management
- `bitcoin_transactions.py`: Transaction analysis utilities
- `bitcoin_utils.py`: Blockchain utilities
- `bitcoin_analytics.py`: Advanced blockchain analytics
- `bitfeed.py`: 3D representations of BTC blocks
## Security Notes
- This mcp server **does not** include wallet functionality in Bitcoin Core (u can add those urself)
- By default, the server only binds to localhost (127.0.0.1)
- Enables read-only access to blockchain data
## Example Usage
Get current blockchain information:
```
Tell me about the current state of the Bitcoin blockchain
```
Analyze a specific block:
```
Show me detailed information about block 800000
```
Get transaction fee history:
```
What have transaction fees been like over the past 24 hours?
```
Estimate hashrate:
```
What is the current estimated hashrate of the Bitcoin network?
```
Generate 3D representation (note that context length may not fit all TXs, try blocks where TX number < 20 ):
```
Build a react threejs viewer for btc block 111111
```
## License
MIT License
