xendit-mcp

# xendit-mcp

[![npm version](https://img.shields.io/npm/v/xendit-mcp.svg)](https://www.npmjs.com/package/xendit-mcp)
[![npm downloads](https://img.shields.io/npm/dm/xendit-mcp.svg)](https://www.npmjs.com/package/xendit-mcp)
[![MCP Badge](https://lobehub.com/badge/mcp/mrslbt-xendit-mcp)](https://lobehub.com/mcp/mrslbt-xendit-mcp)
[![xendit-mcp MCP server](https://glama.ai/mcp/servers/mrslbt/xendit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mrslbt/xendit-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Model Context Protocol server for the [Xendit](https://www.xendit.co/) payment API. Supports payment links via invoices, payouts/disbursements, balances, and transactions across Indonesia, the Philippines, Thailand, Vietnam, and Malaysia.

## Install

```bash
npm install -g xendit-mcp
```

Or run on demand with `npx xendit-mcp`.

## Upgrading from 0.1.x

**0.2.0 introduces breaking defaults.** If you were on `0.1.x` and relied on invoice creation or one-shot payouts working out of the box, those tools are now disabled by default.

To restore the old behavior, set these in your MCP config `env`:

```
XENDIT_ENABLE_INVOICE_MUTATIONS=true
XENDIT_ENABLE_DISBURSEMENTS=true
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true
```

If you enable disbursements, you must also set the four safety gates (`XENDIT_MAX_DISBURSEMENT_AMOUNT`, `XENDIT_MAX_DAILY_AMOUNT`, `XENDIT_ALLOWED_ACCOUNTS`, `XENDIT_APPROVAL_CODE`) or the server will refuse to start.

The recommended migration is to adopt the new two-step payout flow (`prepare_disbursement` → `confirm_disbursement` with an approval code) instead of re-enabling the legacy one-shot. See [Safety](#safety) for details.

## User-facing modes

Think about the product in 3 modes:

- `read-only`: balances, invoices read, transactions read
- `invoices`: read-only plus `create_invoice` and `expire_invoice`
- `guarded-payouts`: invoices mode plus `prepare_disbursement` and `confirm_disbursement`

For non-technical users, the easiest helpers are:

```bash
npx xendit-mcp doctor
npx xendit-mcp setup
```

- `doctor` prints the current mode, enabled capabilities, and what is still blocked.
- `setup` generates a Claude Code or Claude Desktop snippet for the mode you want.

## Configuration

1. Sign up at the [Xendit Dashboard](https://dashboard.xendit.co/).
2. Go to Settings → API Keys and generate a key.
3. Use a test key (`xnd_development_...`) for development or a live key for production.

| Variable | Required | Description |
|---|---|---|
| `XENDIT_API_KEY` | yes | Test or live API key |
| `XENDIT_ENABLE_INVOICE_MUTATIONS` | no | Set to `true` to enable `create_invoice`, `expire_invoice`, and the `create_payment_link` prompt. Disabled by default for safer read-only behavior. |
| `XENDIT_ENABLE_DISBURSEMENTS` | no | Set to `true` to enable disbursement tools (money-movement). Disabled by default. |
| `XENDIT_ALLOW_LIVE` | no | Set to `true` to allow live/production keys (prefixes `xnd_production_`, `iluma_production_`, `sk_live_`). Refused by default. |
| `XENDIT_MAX_DISBURSEMENT_AMOUNT` | no | Hard cap for one money-out call. Set to `0` or omit to disable. |
| `XENDIT_MAX_DAILY_AMOUNT` | no | Rolling 24-hour cap across money-out calls. Set to `0` or omit to disable. |
| `XENDIT_ALLOWED_ACCOUNTS` | no | Comma-separated allowlist in `CHANNEL_CODE:ACCOUNT_NUMBER` format, e.g. `ID_BCA:1234567890`. |
| `XENDIT_PREPARE_TTL_SECONDS` | no | How long a prepared disbursement token stays valid. Defaults to `300`, max `86400`. |
| `XENDIT_APPROVAL_CODE` | no | Required when `XENDIT_ENABLE_DISBURSEMENTS=true`. Human approval code required by `confirm_disbursement` and legacy one-shot payouts. Keep it out of untrusted prompt context. |
| `XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT` | no | Set to `true` only if you intentionally want the old `create_disbursement` one-shot tool. Disabled by default. |

### Guided setup

If you do not want to hand-edit env vars, run:

```bash
npx xendit-mcp setup
```

It will ask which client you use and which mode you want, then output a ready-to-paste Claude config snippet with placeholders for secrets.

If the MCP is already connected in Claude, you can also ask Claude to use:

- `get_workspace_mode`
- `guided_setup`

`guided_setup` uses MCP elicitation in Claude Code when available, so the user sees a form instead of raw config details.

### Claude Desktop

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "xendit": {
      "command": "npx",
      "args": ["-y", "xendit-mcp"],
      "env": {
        "XENDIT_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add xendit --env XENDIT_API_KEY=your-api-key -- npx -y xendit-mcp
```

### Cursor

Add to `~/.cursor/mcp.json` with the same shape as Claude Desktop.

## Tools

| Tool | Description |
|---|---|
| `get_workspace_mode` | Explain which Xendit mode is active, what is enabled, and the safest next step to unlock more features. |
| `guided_setup` | Generate a Claude Code or Claude Desktop config snippet for `read-only`, `invoices`, or `guarded-payouts`. |
| `get_balance` | Account balance by type (CASH, HOLDING, TAX). |
| `list_invoices` | List invoices filtered by status, date range, or currency. |
| `get_invoice` | Retrieve a single invoice. |
| `create_invoice` | Create a payment invoice and return a payment link. Disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`. |
| `expire_invoice` | Expire an active invoice. Disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`. |
| `list_transactions` | List payments, payouts, refunds, transfers, and balance adjustments. |
| `prepare_disbursement` | Stage a money-out call and return a short-lived confirmation token. **Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.** |
| `confirm_disbursement` | Execute a previously prepared money-out token. Requires `approvalCode`. **Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.** |
| `cancel_disbursement` | Cancel a prepared money-out token. **Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.** |
| `create_disbursement` | Legacy one-shot payout/disbursement. Requires `approvalCode` and explicit legacy opt-in. **Disabled unless both `XENDIT_ENABLE_DISBURSEMENTS=true` and `XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true`.** |
| `get_disbursement` | Check payout/disbursement status. **Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.** |
| `list_disbursement_banks` | List payout channels such as `ID_BCA` and `PH_BPI`. **Disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.** |

## Prompts

| Prompt | Description |
|---|---|
| `check_balance` | Report account balance. |
| `recent_payments` | Payments received in the last N days. |
| `create_payment_link` | Generate a payment link for a customer. Disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`. |
| `unpaid_invoices` | List pending invoices. |
| `daily_summary` | Today's payment activity. |

## Resources

| Resource | URI | Description |
|---|---|---|
| Supported Banks | `xendit://banks` | Common payout channel aliases for Indonesia and the Philippines. |
| Setup Guide | `xendit://setup` | Current mode, setup commands, and plain-English mode explanations. |
| API Info | `xendit://info` | Xendit API overview and doc links. |

## Example queries

```
What's my current Xendit balance?
Saldo Xendit saya berapa?

With `XENDIT_ENABLE_INVOICE_MUTATIONS=true`:
Create an invoice for Rp 500,000 for "Website design deposit".
Buatkan invoice Rp 500.000 untuk "Deposit desain website".

Show me all unpaid invoices.
Tampilkan semua invoice yang belum dibayar.

```

With `XENDIT_ENABLE_DISBURSEMENTS=true`:

```
Prepare a Rp 1,000,000 payout to Ahmad at BCA, then wait for my confirmation.
Siapkan payout Rp 1.000.000 ke Ahmad di BCA, lalu tunggu konfirmasi saya.

List available payout channels in the Philippines.
```

## Environments

Xendit issues separate test and live API keys. Test keys operate against the Xendit sandbox, so no real funds move. Live keys (`xnd_production_...`, `iluma_production_...`, `sk_live_...`) operate against production.

## Safety

This server can move real money through the Xendit API. Key safeguards:

- **Read-only by default.** Invoice write tools are disabled unless `XENDIT_ENABLE_INVOICE_MUTATIONS=true`. Money-moving tools are disabled unless `XENDIT_ENABLE_DISBURSEMENTS=true`.
- **Live keys are refused by default.** Keys with the prefixes `xnd_production_`, `iluma_production_`, or `sk_live_` are rejected at startup unless `XENDIT_ALLOW_LIVE=true`. Always test with a development key (`xnd_development_...`) first.
- **Fail-closed money movement.** If you enable disbursements, the server refuses to start unless `XENDIT_MAX_DISBURSEMENT_AMOUNT`, `XENDIT_MAX_DAILY_AMOUNT`, `XENDIT_ALLOWED_ACCOUNTS`, and `XENDIT_APPROVAL_CODE` are configured.
- **Human-in-the-loop flow.** `confirm_disbursement` requires both the staged token and a separate `approvalCode`.
- **Legacy one-shot payouts stay off by default.** `create_disbursement` is not even registered unless `XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true`.
- **Hard caps and allowlists.** `XENDIT_MAX_DISBURSEMENT_AMOUNT`, `XENDIT_MAX_DAILY_AMOUNT`, and `XENDIT_ALLOWED_ACCOUNTS` let you fail closed before a payout is sent.
- **Idempotency.** Payout calls use your `externalId` as the `Idempotency-Key`, so safe retries do not create duplicate transfers.
- **Setup helpers are always available.** `get_workspace_mode` and `guided_setup` are exposed even in read-only mode so users can understand what is blocked and how to enable the next mode safely.
- **Important limitation.** No MCP server can be fully immune to prompt injection if you expose sensitive read or write tools to an untrusted model context. These defaults reduce risk, but you should still only connect this server to trusted agent workflows.

Even with these gates on, review any money-moving request before approving the tool call. Treat tool inputs derived from model