MCP Bitcoin CLI

<p align="center"> <h1 align="center">MCP Bitcoin CLI</h1> <p align="center"> <strong>Embed and read data on the Bitcoin blockchain through Claude</strong> </p> <p align="center"> <a href="https://github.com/EricGrill/mcp-bitcoin-cli/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a> <img src="https://img.shields.io/badge/tools-16-green.svg" alt="16 Tools"> <img src="https://img.shields.io/badge/OP__RETURN-100KB-orange.svg" alt="OP_RETURN 100KB"> <img src="https://img.shields.io/badge/python-%3E%3D3.11-blue.svg" alt="Python >= 3.11"> </p> <p align="center"> <a href="#-quick-start">Quick Start</a> | <a href="#-available-tools">Tools</a> | <a href="#%EF%B8%8F-configuration">Configuration</a> | <a href="#-contributing">Contributing</a> </p> </p>

---

What is this?

An MCP (Model Context Protocol) server that enables Claude to interact with Bitcoin's OP_RETURN functionality. Store documents, create timestamps, deploy tokens, and build custom protocols—all through natural language.

Works with Claude Desktop, Cursor, and any MCP-compatible client.

Supports Bitcoin Core v30+ with up to ~100KB OP_RETURN data.

---

Quick Start

# Install from source
git clone https://github.com/EricGrill/mcp-bitcoin-cli.git
cd mcp-bitcoin-cli
pip install -e .

# Run the server
mcp-bitcoin-cli

Add to your Claude Desktop config and start working with Bitcoin:

"Create a timestamp for this document on Bitcoin testnet"

---

Why Use This?

Feature	Description
Document Storage	Embed documents up to 100KB directly on-chain
Timestamping	Create immutable SHA-256/SHA3 hash commitments
BRC-20 Tokens	Deploy, mint, and transfer tokens using the BRC-20 standard
Custom Protocols	Build your own OP_RETURN protocols with the BTCD envelope format
Offline-Capable	Encode/decode data without a running Bitcoin node
Safety First	Testnet default, dry-run mode, fee warnings

---

Available Tools

Low-Level Primitives

Offline-capable tools for data encoding and transaction building.

Tool	Description
encode_op_return	Encode arbitrary data into OP_RETURN script format
decode_op_return	Parse and extract data from OP_RETURN scripts
build_op_return_transaction	Construct transactions with OP_RETURN outputs
parse_envelope	Parse BTCD envelope structure from raw bytes

Bitcoin Core Interface

Tools for interacting with a running Bitcoin node.

Tool	Description
get_node_info	Check connection status and network info
list_utxos	List available UTXOs for funding transactions
broadcast_transaction	Send signed transactions (dry-run by default)
get_transaction	Fetch and decode transaction details
search_op_returns	Scan blocks for OP_RETURN transactions

Token Operations (BRC-20)

Create and manage tokens using the BRC-20 standard.

Tool	Description
create_token_deploy	Deploy a new BRC-20 token
create_token_mint	Mint tokens from an existing deployment
create_token_transfer	Create a transfer inscription

Document Storage

Store and retrieve documents on the blockchain.

Tool	Description
embed_document	Prepare documents for on-chain storage
read_document	Parse and extract documents from transactions

Timestamping & Attestation

Create cryptographic proofs of existence.

Tool	Description
create_timestamp	Create SHA-256/SHA3 hash commitments
verify_timestamp	Verify data against on-chain timestamps

---

Data Envelope Format

All data uses the BTCD envelope format for discoverability and proper parsing:

┌─────────────────────────────────────────────────────────┐
│ OP_RETURN Envelope (variable size, up to ~100KB)        │
├──────────┬──────────┬──────────┬────────────────────────┤
│ Magic    │ Version  │ Type     │ Payload                │
│ (4 bytes)│ (1 byte) │ (1 byte) │ (variable)             │
├──────────┼──────────┼──────────┼────────────────────────┤
│ "BTCD"   │ 0x01     │ See below│ Type-specific data     │
└──────────┴──────────┴──────────┴────────────────────────┘

Type	Hex	Description
RAW	0x00	Raw bytes, no structure
TEXT	0x01	UTF-8 text
JSON	0x02	JSON document
HASH	0x03	Hash commitment (timestamp)
TOKEN	0x04	Token operation (BRC-20)
FILE	0x05	File with content-type
CUSTOM	0x80+	User-defined protocols

---

Configuration

Claude Desktop Setup

Add to your Claude Desktop config:

Platform	Config Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitcoin": {
      "command": "mcp-bitcoin-cli",
      "env": {
        "BITCOIN_NETWORK": "testnet",
        "BITCOIN_CLI_PATH": "/usr/local/bin/bitcoin-cli"
      }
    }
  }
}

Configuration File

Create ~/.mcp-bitcoin-cli/config.toml:

[connection]
method = "cli"              # "cli" or "rpc"
network = "testnet"         # "mainnet", "testnet", "signet", "regtest"

[cli]
path = "bitcoin-cli"        # Path to bitcoin-cli binary
datadir = ""                # Optional: custom datadir

[rpc]
host = "127.0.0.1"
port = 18332                # Testnet default
user = ""
password = ""

[safety]
require_confirmation = true # Prompt before broadcast
dry_run_default = true      # Always dry-run first
max_data_size = 102400      # 100KB limit

Network Ports

Network	Default RPC Port
Mainnet	8332
Testnet	18332
Signet	38332
Regtest	18443

---

Examples

<details> <summary><b>Timestamping</b></summary>

"Create a SHA-256 timestamp for this contract"
"Verify this document against timestamp in transaction abc123..."
"Create a SHA3-256 hash commitment for my research paper"

</details>

<details> <summary><b>Document Storage</b></summary>

"Embed this JSON configuration on the blockchain"
"Store this text document with content-type text/plain"
"Read the document from transaction def456..."

</details>

<details> <summary><b>BRC-20 Tokens</b></summary>

"Deploy a new token called TEST with max supply 21 million"
"Mint 1000 TEST tokens"
"Create a transfer inscription for 500 TEST"

</details>

<details> <summary><b>Raw Data</b></summary>

"Encode this hex data into an OP_RETURN script"
"Decode the OP_RETURN from this transaction"
"Build a transaction with this message embedded"

</details>

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Server                           │
├─────────────────────────────────────────────────────────┤
│  High-Level Tools                                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐   │
│  │ BRC-20 Ops  │ │ Document    │ │ Timestamp/      │   │
│  │ deploy/mint │ │ Storage     │ │ Attestation     │   │
│  └──────┬──────┘ └──────┬──────┘ └────────┬────────┘   │
│         │               │                  │            │
│  ───────┴───────────────┴──────────────────┴─────────  │
│                                                         │
│  Low-Level Primitives                                   │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐   │
│  │ encode_     │ │ decode_     │ │ build_op_return │   │
│  │ op_return   │ │ op_return   │ │ _transaction    │   │
│  └─────────────┘ └─────────────┘ └─────────────────┘   │
├─────────────────────────────────────────────────────────┤
│  Bitcoin Core Interface (configurable)                  │
│  ┌──────────────────┐  ┌────────────────────────────┐  │
│  │ bitcoin-cli      │  │ JSON-RPC (direct)          │  │
│  │ (subprocess)     │  │                            │  │
│  └──────────────────┘  └────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

---

Safety Features

Feature	Description
Testnet Default	Network locked to testnet unless explicitly configured
Dry-Run Mode	Transactions validated before broadcast by default
Fee Warnings	Alerts for unusually high fees
Size Validation	Rejects data exceeding configured max before building
Network Lock	Can't switch networks mid-session

---

Development

# Clone
git clone https://github.com/EricGrill/mcp-bitcoin-cli.git
cd mcp-bitcoin-cli

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=mcp_bitcoin_cli

Project Structure

src/mcp_bitcoin_cli/
├── __init__.py          # Public exports
├── server.py            # MCP server with 16 tools
├── envelope.py          # BTCD envelope encoding/decoding
├── primitives.py        # OP_RETURN script encoding/decoding
├── config.py            # Configuration loading
├── node/
│   ├── interface.py     # Abstract node interface
│   ├── cli.py           # bitcoin-cli subprocess
│   └── rpc.py           # JSON-RPC direct connection
└── protocols/
    ├── base.py          # Base protocol class
    └── brc20.py         # BRC-20 token protocol

---

Troubleshooting

<details> <summary><b>Cannot connect to Bitcoin Core</b></summary>

1. Verify Bitcoin Core is running: bitcoin-cli getblockchaininfo
2. Check network matches config (testnet vs mainnet)
3. Verify RPC credentials if using JSON-RPC mode

</details>

<details> <summary><b>Transaction rejected</b></summary>

1. Use broadcast_transaction with dry_run=true first
2. Check fee rate is sufficient
3. Verify UTXOs have enough confirmations

</details>

<details> <summary><b>Data too large</b></summary>

• Bitcoin Core v30+ supports up to ~100KB OP_RETURN
• Older versions limited to 80 bytes
• Check max_data_size in config

</details>

<details> <summary><b>Import errors</b></summary>

# Verify installation
python -c "import mcp_bitcoin_cli; print(mcp_bitcoin_cli.__version__)"

# Reinstall if needed
pip install -e ".[dev]"

</details>

---

Contributing

Contributions welcome!

1. Fork the repository
2. Create feature branch: git checkout -b feature/my-feature
3. Make changes and test: pytest
4. Commit: git commit -m 'Add my feature'
5. Push: git push origin feature/my-feature
6. Open a Pull Request

---

Related Projects

• MCP Proxmox Admin - Manage Proxmox VE through Claude
• Model Context Protocol - The protocol specification
• BRC-20 Standard - Bitcoin token standard

---

License

MIT