MCP HubMCP Hub
zebedeeio

zbd-mcp-server

by: zebedeeio

ZBD MCP Server

4created 09/03/2025
Visit

📌Overview

Purpose: The ZBD MCP Server aims to integrate Bitcoin payment capabilities into language models, enhancing their functionality with seamless payment processing.

Overview: The ZBD MCP Server leverages the official TypeScript SDK to provide a modular framework for building tools that interact with the ZBD API, allowing for straightforward handling of Bitcoin Lightning payments and related functionalities.

Key Features:

  • Modular Design: Each tool is encapsulated within its own TypeScript file, promoting a clear project structure and ease of maintenance.

  • Comprehensive Toolset: The server includes a variety of tools for sending payments, creating charges, validating addresses, and managing gamertags, which collectively streamline Bitcoin transaction processes.

  • Executable Generation: It supports building executables for each tool, which can run directly on a client environment, enhancing usability for developers and users alike.

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 done, run the pnpm build command and set up the MCP server on your client (e.g., Claude Desktop or Cursor).

Installing Bun

If you don't have Bun installed, install it as follows:

macOS and Linux

# Using curl (recommended)
curl -fsSL https://bun.sh/install | bash

# Using Homebrew
brew install oven-sh/bun/bun

# Using npm
npm install -g bun

Windows

# Using PowerShell
powershell -c "irm bun.sh/install.ps1|iex"

# Using npm
npm install -g bun

# Using Scoop
scoop install bun

Verify installation by running:

bun --version

Installation

pnpm install

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 instances.

Project Structure

  • 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 tooling implementation.

Available Tools

  • ZBD (src/zbd.ts): ZBD API for global Bitcoin Lightning payments

Creating New Tool

  1. Create a new TypeScript file in the src directory (e.g., src/mytool.ts).
  2. Use existing tools as templates.
  3. Add a build script to package.json:
"build:mytool": "mkdir -p bin && bun build src/mytool.ts --compile --minify --sourcemap --outfile bin/mcp-mytool"
  1. Update the build:all script to include your new tool.

Usage

Building Executables

# Build all tools
pnpm build

# Build a specific tool
pnpm build:zbd

The resulting executables will be in the bin directory and can be run directly:

./bin/mcp-zbd

Cursor Notes

When using these tools with Cursor, always use the full path to the executable:

/path/to/your/project/bin/mcp-zbd

Alternatively, run TypeScript files directly with Node:

/path/to/node ~/path/to/project/src/index.ts

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

ZBD.ts Tools Available

The following tools are available in the ZBD MCP Server:

  1. send-lightning-payment - Send a Bitcoin Lightning Network payment to a Lightning Address using ZBD
  2. send-gamertag-payment - Send a Bitcoin payment to a ZBD Gamertag
  3. create-gamertag-charge - Generate a payment request for a ZBD User
  4. validate-lightning-address - Verify the validity of a Lightning Address
  5. create-lightning-charge - Generate a payment request for a Lightning Address
  6. get-userid-by-gamertag - Retrieve User ID from a ZBD Gamertag
  7. get-gamertag-by-userid - Retrieve ZBD Gamertag from a User ID
  8. send-email-payment - Send instant Bitcoin payments to any email
  9. get-wallet-info - Retrieve all data about a ZBD Project's Wallet
  10. check-supported-region - Verify if a user is coming from a supported region
  11. get-zbd-ip-addresses - Get the official IP addresses of ZBD servers
  12. internal-transfer - Perform a transfer of funds between two Projects
  13. create-withdrawal-request - Create a Bitcoin withdrawal QR code
  14. get-withdrawal-request - Retrieve all data about a single Withdrawal Request
  15. send-payment - Send a Bitcoin Lightning Network payment
  16. get-payment - Retrieve all data about a single Payment
  17. decode-charge - Understand the inner properties of a Charge QR code
  18. create-charge - Create a new Bitcoin Lightning Network charge
  19. get-charge - Retrieve all data about a single Charge
  20. create-voucher - Create a single-use ZBD Voucher redeemable by any ZBD user
  21. get-voucher - Retrieve details about a ZBD Voucher
  22. redeem-voucher - Redeem a ZBD Voucher to credit your Project wallet
  23. revoke-voucher - Revoke a valid ZBD Voucher and reclaim the sats to your Project wallet
  24. send-batch-lightning-payments - Send multiple Bitcoin Lightning Network payments to Lightning Addresses in a single request