ZBD MCP Server
Add Bitcoin powers to your LLM.
Base SDK
This MCP server uses the official TypeScript SDK -- https://github.com/modelcontextprotocol/typescript-sdk
Prerequisites
- Node.js 23+ (or Bun/Deno/Anything that supports running .ts files)
- Bun (for building executables)
- ZBD API key for payment processing
ZBD Setup
Get your API key from the ZBD Developer Dashboard and put it in a new `.env` file under `ZBD_API_KEY=XXXXXXXXXXXX` (check `.env.example` for an example).
Once that's done run the `pnpm build` command and setup the MCP server on your client (e.g. Claude Desktop or Cursor).
Installing Bun
If you don't have Bun installed, you can install it using one of the following methods:
macOS and Linux
Windows
Verify your installation by running:
Installation
Troubleshooting
- Use `ps aux | grep mcp-zbd | grep -v grep` to list all running ZBD MCP Server instances.
- Use `pkill -f mcp-zbd` to kill any duplicate ZBD MCP Server instances that may linger.
Project Structure
This project demonstrates a modular approach to building MCP tools:
- Each tool is defined in its own TypeScript file in the `src` directory
- Each tool can be built into a standalone executable in the `bin` directory
- The main `index.ts` provides the actual tooling implementation
Available Tools
- **ZBD** (`src/zbd.ts`): ZBD API for global Bitcoin Lightning payments
Creating New Tool
To create a new tool:
- Create a new TypeScript file in the `src` directory (e.g., `src/mytool.ts`)
- Use the existing tools as templates
- Add a build script to `package.json`:
- Update the `build:all` script to include your new tool
Usage
Building Executables
The resulting executables will be in the `bin` directory and can be run directly:
Cursor Notes
When using these tools with Cursor, always use the full path to the executable:
Alternatively, you can run the TypeScript files directly with Node:
Testing
ZBD.ts Tools Available
The following tools are available in the ZBD MCP Server:
- `send-lightning-payment` - Send a Bitcoin Lightning Network payment to a Lightning Address using ZBD
- `send-gamertag-payment` - Send a Bitcoin payment to a ZBD Gamertag
- `create-gamertag-charge` - Generate a payment request for a ZBD User
- `validate-lightning-address` - Verify the validity of a Lightning Address
- `create-lightning-charge` - Generate a payment request for a Lightning Address
- `get-userid-by-gamertag` - Retrieve User ID from a ZBD Gamertag
- `get-gamertag-by-userid` - Retrieve ZBD Gamertag from a User ID
- `send-email-payment` - Send instant Bitcoin payments to any email
- `get-wallet-info` - Retrieve all data about a ZBD Project's Wallet
- `check-supported-region` - Verify if a user is coming from a supported region
- `get-zbd-ip-addresses` - Get the official IP addresses of ZBD servers
- `internal-transfer` - Performs a transfer of funds between two Projects
- `create-withdrawal-request` - Create a Bitcoin withdrawal QR code
- `get-withdrawal-request` - Retrieve all data about a single Withdrawal Request
- `send-payment` - Send a Bitcoin Lightning Network payment
- `get-payment` - Retrieve all data about a single Payment
- `decode-charge` - Understand the inner properties of a Charge QR code
- `create-charge` - Create a new Bitcoin Lightning Network charge
- `get-charge` - Retrieve all data about a single Charge
- `create-voucher` - Create a single-use ZBD Voucher that can be redeemed by any ZBD user
- `get-voucher` - Retrieve details about a ZBD Voucher
- `redeem-voucher` - Redeem a ZBD Voucher to credit your Project wallet
- `revoke-voucher` - Revoke a valid ZBD Voucher and reclaim the sats to your Project wallet
- `send-batch-lightning-payments` - Send multiple Bitcoin Lightning Network payments to Lightning Addresses in a single request