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?

Available Tools

Low-Level Primitives

Offline-capable tools for data encoding and transaction building.

Bitcoin Core Interface

Tools for interacting with a running Bitcoin node.

Token Operations (BRC-20)

Create and manage tokens using the BRC-20 standard.

Document Storage

Store and retrieve documents on the blockchain.

Timestamping & Attestation

Create cryptographic proofs of existence.

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     │
└──────────┴──────────┴──────────┴────────────────────────┘

Configuration

Claude Desktop Setup

Add to your Claude Desktop config:

{
  "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

Examples

"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"

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

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

"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

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

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

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

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