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

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

🚀 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