Bitcoin UTXO MCP

1# Bitcoin UTXO MCP
2 
3An MCP server that tracks Bitcoin's Unspent Transaction Outputs (UTXO) and block statistics, giving AI agents direct access to essential on-chain data.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/bitcoin-utxo-mcp) 
6![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- **Tools**:
12  - `get_utxo`: Retrieves UTXO details for a given Bitcoin address, including the number of UTXOs, total value in BTC, and transaction details.
13  - `get_block_stats`: Fetches transaction statistics for a specific Bitcoin block, including block hash, transaction count, total value, and block time.
14- **Prompt**:
15  - `analyze_bitcoin_flow`: A reusable prompt template for LLMs to analyze Bitcoin funds flow, network health, and potential market impacts based on UTXO and block data.
16 
17## Installation
18 
19### Prerequisites
20 
21- **Python**: Version 3.10 or higher
22- **uv**: A fast and modern Python package manager ([installation instructions](https://docs.astral.sh/uv/))
23 
24### Setup
25 
261. **Clone the Repository**:
27   ```bash
28   git clone https://github.com/kukapay/bitcoin-utxo-mcp.git
29   cd bitcoin-utxo-mcp
30   ```
31 
322. **Install dependencies**:
33   ```bash
34   uv sync
35   ```
36 
373. **Install to Claude Desktop**:
38 
39    Install the server as a Claude Desktop application:
40    ```bash
41    uv run mcp install main.py --name "Bitcoin UTXO"
42    ```
43 
44    Configuration file as a reference:
45 
46    ```json
47    {
48       "mcpServers": {
49           "Bitcoin UTXO": {
50               "command": "uv",
51               "args": [ "--directory", "/path/to/bitcoin-utxo-mcp", "run", "main.py" ]
52           }
53       }
54    }
55    ```
56    Replace `/path/to/bitcoin-utxo-mcp` with your actual installation path.
57 
58 
59## Usage
60 
61### Available Tools and Prompts
62 
63- **Tools**:
64  - `get_utxo(address: str)`: Returns UTXO details for a Bitcoin address, e.g., "Address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa: 50 UTXOs, Total Value: 50.00000000 BTC, UTXO Details: ...".
65  - `get_block_stats(block_height: int)`: Returns block statistics, e.g., "Block Height: 0, Block Hash: 000000000019d668..., Transactions: 1, Total Value: 50.00000000 BTC, Block Time: 1231006505".
66- **Prompt**:
67  - `analyze_bitcoin_flow()`: Generates a prompt for LLMs to analyze UTXO and block data, e.g., "Analyze the provided Bitcoin UTXO and block data: What do the UTXO distributions indicate about funds flow? ...".
68 
69### Example Interaction
70 
71Below are examples of natural language prompts you might use in an MCP-compatible client (e.g., Claude Desktop) and the corresponding outputs from the server, based on hypothetical Blockchain.com API responses.
72 
731. **Get UTXO for a Bitcoin Address**:
74   - **Prompt**: "Show me the UTXO details for the Bitcoin genesis address."
75   - **Command**: `get_utxo("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa")`
76   - **Output**:
77     ```
78     Address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:
79     50 UTXOs
80     Total Value: 50.00000000 BTC
81     UTXO Details:
82     - TXID: 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b, Value: 50.00000000 BTC, Confirmations: 800000
83     ```
84 
852. **Get Block Statistics**:
86   - **Prompt**: "What's the transaction data for the Bitcoin genesis block?"
87   - **Command**: `get_block_stats(0)`
88   - **Output**:
89     ```
90     Block Height: 0
91     Block Hash: 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
92     Transactions: 1
93     Total Value: 50.00000000 BTC
94     Block Time: 1231006505
95     ```
96 
973. **Analyze Bitcoin Flow**:
98   - **Prompt**: "Analyze Bitcoin funds flow and network health."
99   - **Command**: `analyze_bitcoin_flow()`
100   - **Output** (prompt sent to LLM for analysis):
101     ```
102     Analyze the provided Bitcoin UTXO and block data:
103     - What do the UTXO distributions indicate about funds flow?
104     - How does the block statistics reflect network health (e.g., transaction volume, congestion)?
105     - Provide insights on potential market impacts or trends.
106     ```
107     - **LLM Response** (example, depends on the LLM):
108       ```
109       The UTXO distribution for the queried address shows a significant number of unspent outputs, indicating long-term holding behavior, possibly by an early adopter. The genesis block's single transaction with 50 BTC reflects the initial reward structure. Current block statistics suggest stable network health with consistent transaction volumes. High UTXO consolidation may signal preparation for large transfers, potentially impacting market liquidity if moved. Historically, such patterns precede price volatility.
110       ```
111 
112## License
113 
114This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
115 
116