# ⚠️ 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

```bash
# 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

```bash
# 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:

```bash
bun --version
```

## Installation

```bash
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`:

```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

```bash
# 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:

```bash
./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

```bash
# 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