Which integrations are available for this server?

Enables interaction with Bitcoin's OP_RETURN functionality to store documents, create cryptographic timestamps, deploy and manage BRC-20 tokens, and build custom protocols on the Bitcoin blockchain through Bitcoin Core.

How do I use MCP Bitcoin CLI?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Bitcoin CLI create a timestamp for my contract document on testnet" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Bitcoin CLI by EricGrill

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

"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

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

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

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

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

# 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

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

License

MIT

MCP Bitcoin CLI

What is this?

Quick Start

Why Use This?

Available Tools

Low-Level Primitives

Bitcoin Core Interface

Token Operations (BRC-20)

Document Storage

Timestamping & Attestation

Data Envelope Format

Configuration

Claude Desktop Setup

Configuration File

Network Ports

Examples

Architecture

Safety Features

Development

Project Structure

Troubleshooting

Contributing

License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

What is this?

Quick Start

Why Use This?

Available Tools

Low-Level Primitives

Bitcoin Core Interface

Token Operations (BRC-20)

Document Storage

Timestamping & Attestation

Data Envelope Format

Configuration

Claude Desktop Setup

Configuration File

Network Ports

Examples

Architecture

Safety Features

Development

Project Structure

Troubleshooting

Contributing

Related Projects

License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API