MCP Bitcoin CLI
Embed and read data on the Bitcoin blockchain through Claude
= 3.11">
Quick Start | Tools | Configuration | Contributing
______________________________________________________________________
这是什么？
一 MCP（模型上下文协议） 服务器，使Claude能够与比特币的OP_RETURN功能进行交互。通过自然语言存储文档、创建时间戳、部署令牌和构建自定义协议。
适用于Claude Desktop、Cursor和任何兼容MCP的客户端。
支持比特币核心v30+，最大约100KB OP_RETURN数据。
______________________________________________________________________
快速开始
# 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添加到您的Claude Desktop配置中，开始使用比特币：
“在比特币测试网上为此文档创建时间戳”
______________________________________________________________________
为什么使用这个？
| 特性 | 描述 |
|---|---|
| 文档存储 | 直接在链上嵌入高达100KB的文档 |
| 时间戳 | 创建不可变的SHA-256/SHA3哈希承诺 |
| BRC-20代币 | 使用BRC-20标准部署、铸造和转移代币 |
| 自定义协议 | 使用BTCD信封格式构建自己的OP_RETURN协议 |
| 离线功能 | 无需运行比特币节点即可对数据进行编码/解码 |
| 安全第一 | 测试网默认、模拟运行模式、费用警告 |
______________________________________________________________________
可用工具
低级基本体
用于数据编码和事务构建的离线工具。
| 工具 | 说明 |
|---|---|
encode_op_return | 将任意数据编码为OP_RETURN脚本格式 |
decode_op_return | 从OP_RETURN脚本中解析和提取数据 |
build_op_return_transaction | 使用OP_RETURN输出构建事务 |
parse_envelope | 从原始字节解析BTCD信封结构 |
比特币核心接口
用于与正在运行的比特币节点交互的工具。
| 工具 | 说明 |
|---|---|
get_node_info | 检查连接状态和网络信息 |
list_utxos | 列出可用于融资交易的UTXO |
broadcast_transaction | 发送已签名的交易（默认情况下为模拟运行） |
get_transaction | 获取并解码交易详细信息 |
search_op_returns | 扫描OP_RETURN交易的区块 |
代币操作（BRC-20）
使用创建和管理令牌 BRC-20标准.
| 工具 | 说明 |
|---|---|
create_token_deploy | 部署新的BRC-20令牌 |
create_token_mint | 从现有部署中铸造代币 |
create_token_transfer | 创建转账题词 |
文档存储
在区块链上存储和检索文档。
| 工具 | 说明 |
|---|---|
embed_document | 准备链上存储文件 |
read_document | 从交易中解析和提取文档 |
时间戳和证明
创建存在的加密证明。
| 工具 | 说明 |
|---|---|
create_timestamp | 创建SHA-256/SHA3哈希承诺 |
verify_timestamp | 根据链上时间戳验证数据 |
______________________________________________________________________
数据信封格式
所有数据均使用 BTCD信封格式 为了便于发现和正确解析：
┌─────────────────────────────────────────────────────────┐
│ 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 │
└──────────┴──────────┴──────────┴────────────────────────┘| 类型 | 十六进制 | 描述 |
|---|---|---|
| 生的 | 0x00 | 原始字节，无结构 |
| 文本 | 0x01 | UTF-8文本 |
| JSON | 0x02 | JSON文档 |
| 哈希 | 0x03 | 哈希承诺（时间戳） |
| 代币 | 0x04 | 令牌操作（BRC-20） |
| 文件 | 0x05 | 具有内容类型的文件 |
| 定制 | 0x80+ | 用户定义协议 |
______________________________________________________________________
配置
Claude桌面设置
添加到您的Claude Desktop配置中：
| 平台 | 配置路径 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| 窗户 | %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"
}
}
}
}配置文件
创建 ~/.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网络端口
| 网络 | 默认RPC端口 |
|---|---|
| 主网 | 8332 |
| 测试网 | 18332 |
| 签名 | 38332 |
好的，18443。
______________________________________________________________________
例子
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"______________________________________________________________________
建筑
┌─────────────────────────────────────────────────────────┐
│ 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) │ │ │ │
│ └──────────────────┘ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘______________________________________________________________________
安全功能
| 特性 | 描述 |
|---|---|
| 测试网默认值 | 除非明确配置，否则网络锁定到测试网 |
| 干运行模式 | 默认情况下，交易在广播前已验证 |
| 费用警告 | 异常高费用的警报 |
| 尺寸验证 | 生成前拒绝超过配置最大值的数据 |
| 网络锁定 | 会话中无法切换网络 |
______________________________________________________________________
发展
# 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项目结构
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______________________________________________________________________
故障排除
Cannot connect to Bitcoin Core
- 验证比特币核心是否正在运行：
bitcoin-cli getblockchaininfo - 检查网络匹配配置（测试网与主网）
- 如果使用JSON-RPC模式，请验证RPC凭据
Transaction rejected
- 使用
broadcast_transaction随着dry_run=true第一 - 检查费率是否足够
- 验证UTXO是否有足够的确认
Data too large
- 比特币核心v30+支持高达~100KB的OP_RETURN
- 旧版本限制为80字节
- 检查
max_data_size在配置中
Import errors
# Verify installation
python -c "import mcp_bitcoin_cli; print(mcp_bitcoin_cli.__version__)"
# Reinstall if needed
pip install -e ".[dev]"______________________________________________________________________
贡献
欢迎投稿！
- 分叉存储库
- 创建要素分支：
git checkout -b feature/my-feature - 进行更改和测试：
pytest - 承诺：
git commit -m 'Add my feature' - 推：
git push origin feature/my-feature - 打开拉取请求
______________________________________________________________________
相关项目
- MCP Proxmox管理员 -通过Claude管理Proxmox VE
- 模型上下文协议 -协议规范
- BRC-20标准 -比特币代币标准
______________________________________________________________________
许可证
麻省理工学院