# 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
```json
{
"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
```bash
# 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
```bash
# 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
```bash
# 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
```json
{
"tool": "wallet_create",
"input": { "network": "testnet", "type": "seed" }
}
```
### Get Free Testnet Coins
```json
{
"tool": "get_testnet_satoshis",
"input": { "walletId": "wif:testnet:cNfsP..." }
}
```
### Send BCH
```json
{
"tool": "send",
"input": {
"walletId": "wif:testnet:...",
"to": [
{ "cashaddr": "bchtest:qq...", "value": 1000, "unit": "sat" }
]
}
}
```
### Create CashToken
```json
{
"tool": "token_genesis",
"input": {
"walletId": "wif:testnet:...",
"amount": "1000000",
"capability": "minting"
}
}
```
### Create Escrow Contract
```json
{
"tool": "escrow_create",
"input": {
"arbiterAddr": "bchtest:qq...",
"buyerAddr": "bchtest:qq...",
"sellerAddr": "bchtest:qq...",
"amount": "50000",
"network": "testnet"
}
}
```
---
## 📦 Monitoring
```bash
# Check server health
curl https://mcp.cashlabs.dev/health
# View container logs
docker logs -f bch-mcp-server
```
---
## 🔄 Updating
```bash
# 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](https://github.com/nickthelegend)
