⚠️ DEPRECATION NOTICE

🚨 This MCP Server is no longer maintained. 🚨

We’ve moved to a new and improved MCP Server implementation. All future updates, features, and support will be provided there.

👉 Please migrate to the new MCP Server here: https://github.com/zebedeeio/zbd-payments-typescript-sdk/tree/main/packages/mcp-server

This repo will remain available for reference, but is not recommended for production use.

ZBD MCP Server (deprecated -- use this instead: https://github.com/zebedeeio/zbd-payments-typescript-sdk/tree/main/packages/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

# 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 your 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 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

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

Creating New Tool

To create a new tool:

1. Create a new TypeScript file in the `src` directory (e.g., `src/mytool.ts`)

2. Use the 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"

4. 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, you can run the 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` - Performs 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 that can be redeemed 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