MCP Bitcoin CLI Server

You can embed data, create cryptographic timestamps, manage tokens, and build custom on-chain protocols by running a dedicated MCP server that talks to Bitcoin via OP_RETURN. This server lets Claude and MCP-compatible clients store and read data on Bitcoin, while keeping safety features and offline-capable tooling for a smooth workflow.

How to use

You interact with the MCP Bitcoin CLI server through an MCP-enabled client. Start the local server, then issue natural language actions like creating a timestamp, embedding a document, or deploying a token. Your client translates your requests into on-chain operations, while the server handles encoding data into the BTCD envelope and coordinating with Bitcoin Core or a CLI interface.

How to install

Prerequisites: Python installed on your system. A Bitcoin Core node is optional if you plan to run a direct RPC connection; otherwise you can operate in offline mode with encoding/decoding tooling.

# 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

Configuration and usage notes

Configure how you connect to Bitcoin and where you run the client. You can use a CLI-based connection to a local Bitcoin node or JSON-RPC if you prefer direct network access. The server defaults to testnet for safety, and it will prompt for confirmations before broadcasting transactions.

If you need to adjust the network or path to the Bitcoin CLI, set the appropriate options in your environment or configuration file. For example, specify the testnet or mainnet and point to the bitcoin-cli binary you want to use.

Examples of common workflows

Timestamping a document on Bitcoin to commit to a specific point in time, embedding a document for on-chain storage, or creating a transfer inscription for BRC-20 tokens are typical flows you can perform once the server is running and your client is configured.

You can also read back on-chain data, verify timestamps, and interact with token deployments or mints using natural language commands that your MCP client translates into the appropriate on-chain actions.

Notes on data formats and safety

All on-chain data uses the BTCD envelope format, which standardizes how metadata, type, and payload are encoded for easy parsing.

Safety features include a testnet default, dry-run mode to validate transactions before broadcasting, and warnings if fees seem unusually high or if a data size limit is exceeded.

Troubleshooting tips

If you encounter connection issues, verify that Bitcoin Core or your chosen node is reachable and that network settings (testnet/mainnet) match your configuration. Ensure RPC credentials are correct if using a direct JSON-RPC connection.

If a transaction is rejected, run through a dry run first, check the fee rate, and confirm that the involved UTXOs have enough confirmations.

Architecture overview

The MCP server provides low-level primitives for encoding OP_RETURN data, building transactions, and parsing BTCD envelopes, plus a Bitcoin Core interface that can be wired via a CLI subprocess or a direct JSON-RPC connection.

Available tools

encode_op_return

Encode arbitrary data into OP_RETURN script format for on-chain embedding.

decode_op_return

Parse and extract data from OP_RETURN scripts.

build_op_return_transaction

Construct transactions that include OP_RETURN outputs.

parse_envelope

Parse BTCD envelope structure from raw bytes.

get_node_info

Check connection status and network info for the Bitcoin node.

list_utxos

List available UTXOs for funding transactions.

broadcast_transaction

Broadcast signed transactions to the network (dry-run by default).

get_transaction

Fetch and decode details of a specific transaction.

search_op_returns

Scan blocks for OP_RETURN transactions.

create_token_deploy

Deploy a new BRC-20 token.

create_token_mint

Mint tokens for an existing BRC-20 deployment.

create_token_transfer

Create a transfer inscription for BRC-20 tokens.

embed_document

Prepare documents for on-chain storage.

read_document

Read and parse documents embedded on-chain.

create_timestamp

Create a cryptographic timestamp for data (SHA-256/SHA3).

verify_timestamp

Verify data against an on-chain timestamp.