<p align="center">
  <h1 align="center">MCP Bitcoin CLI</h1>
  <p align="center">
    <strong>Embed and read data on the Bitcoin blockchain through Claude</strong>
  </p>
  <p align="center">
    <a href="https://github.com/EricGrill/mcp-bitcoin-cli/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
    <img src="https://img.shields.io/badge/tools-16-green.svg" alt="16 Tools">
    <img src="https://img.shields.io/badge/OP__RETURN-100KB-orange.svg" alt="OP_RETURN 100KB">
    <img src="https://img.shields.io/badge/python-%3E%3D3.11-blue.svg" alt="Python >= 3.11">
  </p>
  <p align="center">
    <a href="#-quick-start">Quick Start</a> |
    <a href="#-available-tools">Tools</a> |
    <a href="#%EF%B8%8F-configuration">Configuration</a> |
    <a href="#-contributing">Contributing</a>
  </p>
</p>

---

## What is this?

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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

```bash
# 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](https://domo-2.gitbook.io/brc-20-experiment/).

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

```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`:

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

<details>
<summary><b>Timestamping</b></summary>

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

</details>

<details>
<summary><b>Document Storage</b></summary>

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

</details>

<details>
<summary><b>BRC-20 Tokens</b></summary>

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

</details>

<details>
<summary><b>Raw Data</b></summary>

```
"Encode this hex data into an OP_RETURN script"
"Decode the OP_RETURN from this transaction"
"Build a transaction with this message embedded"
```

</details>

---

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

```bash
# 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

<details>
<summary><b>Cannot connect to Bitcoin Core</b></summary>

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

</details>

<details>
<summary><b>Transaction rejected</b></summary>

1. Use `broadcast_transaction` with `dry_run=true` first
2. Check fee rate is sufficient
3. Verify UTXOs have enough confirmations

</details>

<details>
<summary><b>Data too large</b></summary>

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

</details>

<details>
<summary><b>Import errors</b></summary>

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

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

</details>

---

## 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](https://github.com/EricGrill/mcp-proxmox-admin) - Manage Proxmox VE through Claude
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [BRC-20 Standard](https://domo-2.gitbook.io/brc-20-experiment/) - Bitcoin token standard

---

## License

MIT