AI导哈

比特币命令行工具

一个通过Claude与比特币区块链交互的工具，支持文档存储、时间戳创建、代币部署和自定义协议构建。

  • by EricGrill
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 EricGrill/mcp-bitcoin-cli

使用说明

MCP Bitcoin CLI

Embed and read data on the Bitcoin blockchain through Claude

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
  1. 验证比特币核心是否正在运行： bitcoin-cli getblockchaininfo
  2. 检查网络匹配配置（测试网与主网）
  3. 如果使用JSON-RPC模式，请验证RPC凭据
Transaction rejected
  1. 使用 broadcast_transaction 随着 dry_run=true 第一
  2. 检查费率是否足够
  3. 验证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]"

贡献

欢迎投稿！

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature/my-feature
  3. 进行更改和测试： pytest
  4. 承诺： git commit -m 'Add my feature'
  5. 推： git push origin feature/my-feature
  6. 打开拉取请求

相关项目

许可证

麻省理工学院

相关 MCP