MCP Bitcoin CLI
Embed and read data on the Bitcoin blockchain through Claude
Quick Start | Tools | Configuration | Contributing
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
Timestamping
"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"
Document Storage
"Embed this JSON configuration on the blockchain"
"Store this text document with content-type text/plain"
"Read the document from transaction def456..."
BRC-20 Tokens
"Deploy a new token called TEST with max supply 21 million"
"Mint 1000 TEST tokens"
"Create a transfer inscription for 500 TEST"
Raw Data
"Encode this hex data into an OP_RETURN script"
"Decode the OP_RETURN from this transaction"
"Build a transaction with this message embedded"
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
Cannot connect to Bitcoin Core
- Verify Bitcoin Core is running:
bitcoin-cli getblockchaininfo - Check network matches config (testnet vs mainnet)
- Verify RPC credentials if using JSON-RPC mode
Transaction rejected
- Use
broadcast_transactionwithdry_run=truefirst - Check fee rate is sufficient
- Verify UTXOs have enough confirmations
Data too large
- Bitcoin Core v30+ supports up to ~100KB OP_RETURN
- Older versions limited to 80 bytes
- Check
max_data_sizein config
Import errors
# Verify installation
python -c "import mcp_bitcoin_cli; print(mcp_bitcoin_cli.__version__)"
# Reinstall if needed
pip install -e ".[dev]"
Contributing
Contributions welcome!
- Fork the repository
- Create feature branch:
git checkout -b feature/my-feature - Make changes and test:
pytest - Commit:
git commit -m 'Add my feature' - Push:
git push origin feature/my-feature - 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