BCH MCP Server

A comprehensive Bitcoin Cash (BCH) MCP server powered by mainnet-js. Provides wallet management, balance checking, sending BCH, CashTokens (genesis, minting, burning, sending), escrow contracts, QR codes, and transaction utilities.

🌐 Live Server

Production URL: https://mcp.cashlabs.dev/mcp

Endpoint	URL
MCP Endpoint	https://mcp.cashlabs.dev/mcp
Health Check	https://mcp.cashlabs.dev/health
Server Info	https://mcp.cashlabs.dev/
MCP Card	https://mcp.cashlabs.dev/.well-known/mcp.json

MCP Client Configuration

Standard HTTP MCP configuration. Our server supports Isolated Sessions, meaning every new connection automatically gets a fresh server state, preventing session conflicts:

{
  "mcpServers": {
    "bch-mcp": {
      "url": "https://mcp.cashlabs.dev/mcp"
    }
  }
}

---

📋 Available Tools (40+)

🔐 Wallet Management

Tool	Description	Example Input
wallet_create	Create a new random wallet	{ "network": "testnet", "type": "seed" }
wallet_from_id	Get wallet info from walletId	{ "walletId": "wif:testnet:..." }
wallet_from_seed	Restore wallet from mnemonic	{ "seedPhrase": "word1 word2...", "network": "testnet" }
wallet_from_wif	Restore wallet from WIF private key	{ "wif": "cNfsP...", "network": "testnet" }
wallet_watch_only	Create watch-only wallet	{ "cashaddr": "bchtest:qq...", "network": "testnet" }
get_deposit_address	Get deposit addresses	{ "walletId": "wif:testnet:..." }
get_public_key	Get public key and hash	{ "walletId": "wif:testnet:..." }

💰 Balance & UTXOs

Tool	Description	Example Input
get_balance	Get wallet balance	{ "walletId": "wif:testnet:...", "unit": "bch" }
get_utxos	Get unspent transaction outputs	{ "walletId": "wif:testnet:..." }
get_max_amount_to_send	Get max sendable amount	{ "walletId": "wif:testnet:...", "outputCount": 1 }

📤 Sending Transactions

Tool	Description	Example Input
send	Send BCH to addresses	{ "walletId": "...", "to": [{ "cashaddr": "...", "value": 0.001, "unit": "bch" }] }
send_max	Send all funds to address	{ "walletId": "...", "address": "bchtest:qq..." }
op_return_send	Send with OP_RETURN data	{ "walletId": "...", "data": ["MEMO", "Hello"] }
encode_transaction	Build tx without broadcasting	{ "walletId": "...", "to": [...] }
submit_transaction	Broadcast signed tx hex	{ "walletId": "...", "transactionHex": "0200..." }

📜 History & Blockchain

Tool	Description	Example Input
get_history	Get transaction history	{ "walletId": "...", "unit": "bch", "count": 10 }
get_raw_history	Get raw tx history	{ "walletId": "..." }
get_block_height	Get current block height	{ "network": "testnet" }
decode_transaction	Decode tx by hash/hex	{ "transaction": "abc123...", "loadInputValues": true }

🪙 CashTokens (Fungible & NFT)

Tool	Description	Example Input
token_genesis	Create new token category	{ "walletId": "...", "amount": "1000000", "capability": "minting" }
token_send	Send tokens	{ "walletId": "...", "tokenId": "...", "amount": "100", "cashaddr": "..." }
token_mint	Mint new NFT tokens	{ "walletId": "...", "tokenId": "...", "requests": [...] }
token_burn	Burn tokens	{ "walletId": "...", "tokenId": "...", "amount": "10" }
get_token_balance	Get token balance	{ "walletId": "...", "tokenId": "..." }
get_all_token_balances	Get all FT balances	{ "walletId": "..." }
get_nft_token_balance	Get NFT count	{ "walletId": "...", "tokenId": "..." }
get_all_nft_token_balances	Get all NFT balances	{ "walletId": "..." }
get_token_utxos	Get token UTXOs	{ "walletId": "...", "tokenId": "..." }
get_token_deposit_address	Get token deposit address	{ "walletId": "..." }

🔒 Escrow Contracts

Tool	Description	Example Input
escrow_create	Create escrow contract	{ "arbiterAddr": "...", "buyerAddr": "...", "sellerAddr": "...", "amount": "10000" }
escrow_get_balance	Get escrow balance	{ "contractId": "escrow:testnet:..." }
escrow_spend	Release to seller	{ "contractId": "...", "wif": "..." }
escrow_refund	Refund to buyer	{ "contractId": "...", "wif": "..." }

✍️ Signing & Verification

Tool	Description	Example Input
sign_message	Sign message with wallet	{ "walletId": "...", "message": "Hello World" }
verify_message	Verify message signature	{ "walletId": "...", "message": "...", "signature": "..." }

💱 Price & Conversion

Tool	Description	Example Input
get_bch_price	Get current BCH/USD price	{}
convert_currency	Convert BCH/SAT/USD	{ "amount": 100, "from": "usd", "to": "sat" }

🛠️ Utilities

Tool	Description	Example Input
qr_address	Generate QR code for address	{ "address": "bchtest:qq...", "size": 256 }
validate_address	Validate BCH address	{ "address": "bchtest:qq..." }
wait_for_transaction	Wait for incoming tx	{ "walletId": "..." }
wait_for_balance	Wait for target balance	{ "walletId": "...", "value": 0.01, "unit": "bch" }

🧪 Testnet

Tool	Description	Example Input
get_testnet_satoshis	Get free testnet coins	{ "walletId": "..." }
return_testnet_satoshis	Return coins to faucet	{ "walletId": "..." }

---

📚 MCP Resources (21 Documentation Guides)

Agents can fetch documentation resources for context:

Core Guides

Resource URI	Description
docs://overview	BCH MCP Server overview and quick start
docs://wallets	Wallet management - create, restore, watch-only
docs://transactions	Sending BCH - standard, max, OP_RETURN
docs://cashtokens	CashTokens - genesis, mint, send, burn
docs://escrow	Escrow contracts for secure transactions
docs://utilities	QR codes, price conversion, signing

Reference Guides

Resource URI	Description
docs://bch-basics	Bitcoin Cash fundamentals - units, confirmations
docs://addresses	Address formats - CashAddr, token addresses
docs://smart-contracts	CashScript - escrow, multisig, covenants
docs://bcmr	BCMR - token metadata registries
docs://network	Network info - mainnet, testnet, nodes

Developer Resources

Resource URI	Description
docs://api-reference	Complete API reference for all tools
docs://examples	Code examples for common operations
docs://faq	Frequently asked questions
docs://developer-resources	Tools, APIs, explorers, community
docs://security	Security best practices

CashScript Documentation

Resource URI	Description
docs://cashscript	What is CashScript - smart contract language
docs://cashscript-language	Language reference - types, operators, statements
docs://cashscript-globals	Global variables - tx introspection, time locks
docs://cashscript-covenants	Covenants guide - restrict spending, state
docs://cashscript-sdk	TypeScript SDK - Contract, TransactionBuilder

📚 Comprehensive Project Documentation

The server automatically scans and exposes all documentation files from the project. You can access them using the following URI schemes:

• Mainnet-JS Docs: mainnet://{path/to/file}
• CashScript Docs: cs://{path/to/file}

Examples:

• mainnet://tutorial/rest
• cs://guides/cashtokens

---

🚀 Quick Start

Using the Live Server

Connect your MCP client to https://mcp.cashlabs.dev/mcp

Local Development

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

The server will be available at http://localhost:8081.

Docker

# Build the image
docker build -t bch-mcp-server .

# Run the container
docker run -d -p 8081:8081 --name bch-mcp bch-mcp-server

---

🌍 Deployment to Digital Ocean

Prerequisites

• A Digital Ocean Droplet (Ubuntu 22.04 recommended)
• A domain name (optional, for SSL)
• SSH access to your droplet

Quick Deploy

# SSH into your droplet
ssh root@your-droplet-ip

# Clone the repository
git clone https://github.com/nickthelegend/bch-mcp.git
cd bch-mcp

# Make deployment script executable and run
chmod +x run.sh
./run.sh

DNS Configuration

Add an A Record in your DNS provider:

• Host: mcp (or @ for root)
• Value: Your Droplet's IP address
• TTL: 300

---

📡 API Endpoints

Method	Endpoint	Description
POST	/mcp	Main MCP endpoint for tool calls
GET	/health	Health check endpoint
GET	/	Server info and endpoints
GET	/.well-known/mcp.json	MCP server card (metadata)
GET	/.well-known/mcp-config	MCP configuration schema

---

🔧 Environment Variables

Variable	Default	Description
PORT	8081	Server port
DEBUG	false	Enable debug logging
NODE_ENV	production	Node environment

---

📖 Usage Examples

Create a Testnet Wallet

{
  "tool": "wallet_create",
  "input": { "network": "testnet", "type": "seed" }
}

Get Free Testnet Coins

{
  "tool": "get_testnet_satoshis",
  "input": { "walletId": "wif:testnet:cNfsP..." }
}

Send BCH

{
  "tool": "send",
  "input": {
    "walletId": "wif:testnet:...",
    "to": [
      { "cashaddr": "bchtest:qq...", "value": 1000, "unit": "sat" }
    ]
  }
}

Create CashToken

{
  "tool": "token_genesis",
  "input": {
    "walletId": "wif:testnet:...",
    "amount": "1000000",
    "capability": "minting"
  }
}

Create Escrow Contract

{
  "tool": "escrow_create",
  "input": {
    "arbiterAddr": "bchtest:qq...",
    "buyerAddr": "bchtest:qq...",
    "sellerAddr": "bchtest:qq...",
    "amount": "50000",
    "network": "testnet"
  }
}

---

📦 Monitoring

# Check server health
curl https://mcp.cashlabs.dev/health

# View container logs
docker logs -f bch-mcp-server

---

🔄 Updating

# Pull latest changes
git pull

# Rebuild and restart
docker stop bch-mcp-server
docker rm bch-mcp-server
docker build -t bch-mcp-server .
docker run -d --name bch-mcp-server --network mcp-net --restart unless-stopped -e PORT=8081 bch-mcp-server

---

📜 License

MIT

👤 Author

nickthelegend