Bitnovo Pay MCP Server

resmi

Server MCP untuk integrasi Bitnovo Pay dengan agen AI. Menyediakan kemampuan pembayaran cryptocurrency melalui API Bitnovo Pay. Fitur mencakup pembuatan pembayaran, pengecekan status, pembuatan kode QR, dan manajemen webhook dengan dukungan untuk beberapa penyedia tunnel (ngrok, zrok, manual).

GitHub

Dokumentasi

MCP Bitnovo Pay

Server MCP untuk integrasi Bitnovo Pay dengan agen AI

Server Model Context Protocol (MCP) yang menyediakan kemampuan pembayaran mata uang kripto bagi agen AI melalui integrasi API Bitnovo Pay. Server ini memungkinkan model AI untuk membuat pembayaran, memeriksa status pembayaran, mengelola kode QR, dan mengakses katalog mata uang kripto.

🚀 Fitur

8 Alat MCP untuk manajemen pembayaran yang komprehensif:
- create_payment_onchain - Menghasilkan alamat mata uang kripto untuk pembayaran langsung
- create_payment_link - Membuat URL pembayaran web dengan penanganan pengalihan
- get_payment_status - Meminta status pembayaran dengan informasi terperinci
- list_currencies_catalog - Mendapatkan mata uang kripto yang didukung dengan penyaringan
- generate_payment_qr - Menghasilkan kode QR kustom dari pembayaran yang ada
- get_webhook_events - Meminta peristiwa webhook yang diterima secara real-time
- get_webhook_url - Mendapatkan URL webhook publik dengan instruksi konfigurasi
- get_tunnel_status - Mendiagnosis status koneksi tunnel
Sistem Webhook Otomatis dengan 3 penyedia tunnel:
- 🔗 ngrok: URL persisten gratis (1 domain statis per akun)
- 🌐 zrok: 100% gratis sumber terbuka dengan URL persisten
- 🏢 manual: Untuk server dengan IP publik (N8N, Opal, VPS)
Dukungan Multi-LLM - Kompatibel dengan:
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, Responses API, Agents SDK)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Sept 2025, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
Kode QR Berkualitas Tinggi (v1.1.0+):
- 📱 Resolusi default 512px (naik dari 300px) untuk tampilan modern
- 🖨️ Mendukung hingga 2000px untuk pencetakan profesional
- ✨ Tepi tajam dengan algoritma interpolasi yang dioptimalkan
- 🎨 Branding Bitnovo Pay kustom dengan penskalaan logo yang halus
Privasi Secara Default - Data sensitif disamarkan dalam log, paparan data minimal
Aman - Penegakan HTTPS, validasi tanda tangan HMAC, penanganan rahasia yang aman
Handal - Logika coba ulang bawaan, penanganan waktu habis, operasi tanpa status

📋 Prasyarat

Node.js 18+
Akun Bitnovo Pay dengan ID Perangkat dan Rahasia Perangkat opsional
Konfigurasi Lingkungan (lihat panduan pengaturan di bawah)

⚡ Mulai Cepat

1. Dapatkan Kredensial Bitnovo Anda

Daftar di Bitnovo Pay
Dapatkan ID Perangkat Anda dari dasbor Bitnovo
(Opsional) Hasilkan Rahasia Perangkat untuk validasi tanda tangan webhook

2. Konfigurasikan Klien MCP Anda

Tambahkan konfigurasi ini ke file konfigurasi klien MCP Anda:

Untuk Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Untuk OpenAI ChatGPT (lihat Panduan Pengaturan OpenAI):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

3. Mulai Ulang Klien MCP Anda

Mulai ulang Claude Desktop, ChatGPT, atau klien MCP Anda untuk memuat server.

4. Uji Integrasi

Tanyakan asisten AI Anda: "Buat pembayaran untuk 10 euro"

☁️ Deployment Cloud (BARU di v1.2.0)

MCP Bitnovo Pay sekarang mendukung deployment jarak jauh di platform cloud dengan mode transport HTTP. Ini memungkinkan platform AI seperti claude.ai untuk terhubung ke server MCP Anda dari jarak jauh.

Deploy ke Railway (Direkomendasikan)

Pengaturan Cepat:

Klik "Deploy to Railway" atau buat proyek baru
Atur variabel lingkungan:
- BITNOVO_DEVICE_ID - ID perangkat Bitnovo Anda
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Deploy (Railway mendeteksi Dockerfile secara otomatis)
Dapatkan URL publik Anda: https://your-app.up.railway.app

Hubungkan ke claude.ai:

Tambahkan server di Pengaturan → Model Context Protocol
URL Server: https://your-app.up.railway.app/mcp

📖 Panduan Lengkap: Lihat RAILWAY.md untuk instruksi deployment terperinci, pemecahan masalah, dan konfigurasi.

Deploy ke Docker

# Build the image
docker build -t mcp-bitnovo-pay .

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PORT=3000 \
  -e BITNOVO_DEVICE_ID=your_device_id \
  -e BITNOVO_BASE_URL=https://pos.bitnovo.com \
  mcp-bitnovo-pay

Deploy ke Platform Lain

Server bekerja di platform apa pun yang mendukung Node.js dan Docker:

Heroku: Dorong Dockerfile dengan variabel lingkungan
Fly.io: Deploy dengan konfigurasi fly.toml
Google Cloud Run: Deploy kontainer Docker
AWS ECS/Fargate: Deploy dengan definisi tugas

Variabel Lingkungan yang Diperlukan:

PORT - Port HTTP (diatur otomatis oleh sebagian besar platform)
BITNOVO_DEVICE_ID - ID perangkat Bitnovo Anda
BITNOVO_BASE_URL - URL API Bitnovo

Deteksi Mode Transport:

Jika variabel env PORT diatur → mode HTTP (koneksi jarak jauh)
Jika tidak ada PORT → mode stdio (koneksi lokal)

📦 Opsi Instalasi

Opsi A: Menggunakan npx (Direkomendasikan)

Tidak perlu instalasi! Perintah npx secara otomatis mengunduh dan menjalankan versi terbaru.

npx -y @bitnovopay/mcp-bitnovo-pay

Keuntungan:

✅ Selalu mendapatkan versi terbaru
✅ Tidak perlu pembaruan manual
✅ Tidak perlu instalasi lokal
✅ Langsung berfungsi

Opsi B: Kloning Repositori (Untuk Pengembangan)

Untuk kontributor atau pengguna tingkat lanjut yang perlu memodifikasi kode:

# Clone the repository
git clone https://github.com/bitnovo/mcp-bitnovo-pay.git
cd mcp-bitnovo-pay

# Or install from npm
npm install -g @bitnovopay/mcp-bitnovo-pay

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

Keuntungan:

✅ Kontrol penuh atas kode sumber
✅ Kemampuan untuk memodifikasi dan menguji perubahan
✅ Ideal untuk berkontribusi pada proyek

🔧 Konfigurasi berdasarkan Platform LLM

Pilih platform AI Anda dan ikuti panduan pengaturan spesifik:

Claude Desktop (Anthropic)

Lokasi File Konfigurasi: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Panduan: Panduan Pengaturan Claude

Konfigurasi Dasar:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Dengan Webhook (untuk notifikasi pembayaran real-time):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com",
        "BITNOVO_DEVICE_SECRET": "your_device_secret_hex",
        "WEBHOOK_ENABLED": "true",
        "TUNNEL_ENABLED": "true",
        "TUNNEL_PROVIDER": "ngrok",
        "NGROK_AUTHTOKEN": "your_ngrok_token",
        "NGROK_DOMAIN": "your-domain.ngrok-free.app"
      }
    }
  }
}

OpenAI ChatGPT

Panduan: Panduan Pengaturan OpenAI Didukung: GPT-5, GPT-4o, Responses API, Agents SDK

Konfigurasi Dasar:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Google Gemini

Panduan: Panduan Pengaturan Gemini Didukung: Gemini 2.5 Flash/Pro (Sept 2025), CLI, FastMCP

Konfigurasi Dasar:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Variabel Lingkungan

Variabel	Diperlukan	Deskripsi	Contoh
`BITNOVO_DEVICE_ID`	✅ Ya	Pengidentifikasi perangkat Bitnovo Pay Anda	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ Ya	Endpoint API Bitnovo	`https://pos.bitnovo.com` (produksi) `https://payments.pre-bnvo.com` (pengembangan)
`BITNOVO_DEVICE_SECRET`	⚠️ Opsional	Rahasia HMAC untuk validasi webhook	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ Opsional	Aktifkan server webhook	`true` atau `false`
`TUNNEL_ENABLED`	⚠️ Opsional	Mulai tunnel otomatis untuk webhook	`true` atau `false`
`TUNNEL_PROVIDER`	⚠️ Opsional	Penyedia tunnel	`ngrok`, `zrok`, atau `manual`

Catatan Keamanan: Jangan pernah menyimpan kredensial ke kontrol versi. Gunakan variabel lingkungan atau manajemen rahasia yang aman.

🛠️ Referensi Alat MCP

Pembuatan Pembayaran

`create_payment_onchain`

Membuat pembayaran mata uang kripto dengan alamat spesifik untuk transaksi langsung.

Gunakan saat: Pengguna menentukan mata uang kripto (Bitcoin, ETH, USDC, dll.)

{
  "amount_eur": 50.0,
  "input_currency": "BTC",
  "notes": "Coffee payment"
}

`create_payment_link`

Membuat URL pembayaran berbasis web di mana pelanggan dapat memilih mata uang kripto mereka.

Gunakan saat: Permintaan pembayaran umum tanpa menyebutkan kripto spesifik (OPSI DEFAULT)

{
  "amount_eur": 50.0,
  "url_ok": "https://mystore.com/success",
  "url_ko": "https://mystore.com/cancel",
  "notes": "Order #1234"
}

Manajemen Pembayaran

`get_payment_status`

Mengambil status pembayaran saat ini dengan informasi terperinci.

{
  "identifier": "payment_id_here"
}

Kode Status:

NR (Belum Siap): Pra-pembayaran dibuat, belum ada kripto yang ditetapkan
PE (Tertunda): Menunggu pembayaran pelanggan
AC (Menunggu Penyelesaian): Kripto terdeteksi di mempool
CO (Selesai): Pembayaran dikonfirmasi di blockchain
EX (Kedaluwarsa): Batas waktu pembayaran terlampaui
CA (Dibatalkan): Pembayaran dibatalkan
FA (Gagal): Transaksi gagal dikonfirmasi

`list_currencies_catalog`

Mendapatkan mata uang kripto yang tersedia dengan penyaringan berbasis jumlah opsional.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

Membuat kode QR kustom untuk pembayaran yang ada dengan output berkualitas tinggi.

{
  "identifier": "payment_id_here",
  "qr_type": "both",
  "size": 512,
  "style": "branded"
}

Tipe QR:

address: Hanya alamat kripto (pelanggan memasukkan jumlah secara manual)
payment_uri: Alamat + jumlah disertakan (direkomendasikan)
both: Hasilkan kedua tipe (direkomendasikan)
gateway_url: QR dari URL gateway pembayaran

Opsi Ukuran QR (v1.1.0+):

Default: 512px (dioptimalkan untuk tampilan modern)
Rentang: 100px - 2000px
Ukuran yang direkomendasikan:
- 512px: Tampilan seluler dan web
- 800-1200px: Pencetakan standar
- 1600-2000px: Pencetakan berkualitas tinggi (poster, stand)

Peningkatan Kualitas (v1.1.0):

✨ Tepi tajam dengan interpolasi kernel nearest untuk pola QR
🎯 Penskalaan logo berkualitas tinggi dengan kernel lanczos3
📦 Tingkat kompresi PNG 6 dengan penyaringan adaptif
🖼️ Ukuran default ditingkatkan dari 300px menjadi 512px untuk kejelasan yang lebih baik

Alat Webhook

`get_webhook_events`

Meminta peristiwa webhook yang diterima secara real-time dari API Bitnovo Pay.

Tersedia saat: WEBHOOK_ENABLED=true

{
  "identifier": "payment_id_here",
  "limit": 50,
  "validated_only": true
}

`get_webhook_url`

Mendapatkan URL webhook publik dengan instruksi konfigurasi untuk panel Bitnovo.

Tersedia saat: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Mendiagnosis status koneksi tunnel (ngrok, zrok, atau manual).

Tersedia saat: WEBHOOK_ENABLED=true

{}

📚 Dokumentasi

Referensi Alat API - Dokumentasi terperinci untuk semua alat MCP
Contoh Penggunaan - Contoh penggunaan dunia nyata
Penanganan Kesalahan - Kode kesalahan dan pemecahan masalah
Sistem Webhook - Konfigurasi webhook dan manajemen tunnel

🏗️ Pengembangan

Skrip yang Tersedia

npm run build        # Compile TypeScript to JavaScript
npm run dev          # Run development server with hot reload
npm start            # Start production server
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

Arsitektur

┌─────────────────┐
│   MCP Tools     │ ← 8 tools: 5 payment + 3 webhook
│ (src/tools/)    │
├─────────────────┤
│   Services      │ ← Business logic: PaymentService, CurrencyService
│ (src/services/) │
├─────────────────┤
│   API Client    │ ← Bitnovo API integration with retry logic
│ (src/api/)      │
├─────────────────┤
│ Webhook Server  │ ← HTTP Express + Event Store + Tunnel Manager
│ (src/webhook-*) │
├─────────────────┤
│   Utilities     │ ← Logging, validation, error handling, crypto
│ (src/utils/)    │
└─────────────────┘

Arsitektur Server Ganda

Server MCP dapat menjalankan dua server secara bersamaan:

┌─────────────────────────────────────────────────────────┐
│             MCP Bitnovo Pay Server                      │
│                                                         │
│  ┌──────────────┐  ┌──────────────────┐ ┌────────────┐│
│  │ MCP Server   │  │ Webhook Server   │ │  Tunnel    ││
│  │ (stdio)      │  │ (HTTP :3000)     │ │  Manager   ││
│  └──────┬───────┘  └────────┬─────────┘ └──────┬─────┘│
│         │                   │                   │      │
│         │    Event Store    │     Public URL    │      │
│         │   (in-memory)     │   (ngrok/zrok)    │      │
│         └──────────┬────────┴──────────┬────────┘      │
└────────────────────┼───────────────────┼───────────────┘
                     │                   │
            ┌────────┴────────┐  ┌───────┴────────┐
            │                 │  │                │
       Claude Desktop   Bitnovo API    Tunnel Provider
       (MCP Tools)      (Webhooks)    (ngrok/zrok/manual)

🔒 Keamanan

Hanya HTTPS - Semua panggilan API menggunakan HTTPS
Validasi HMAC - Verifikasi tanda tangan webhook dengan SHA-256
Pencegahan Serangan Ulang - Cache nonce dengan TTL 5 menit
Privasi Data - Informasi sensitif disamarkan dalam log
Tanpa Data Kurs - Kurs pertukaran tidak diekspos untuk mencegah ketidakakuratan
Desain Tanpa Status - Tidak ada persistensi lokal, kueri API real-time
Koneksi Ulang Otomatis - Backoff eksponensial hingga 10 kali coba ulang untuk tunnel
Pemantauan Kesehatan - Verifikasi koneksi setiap 60 detik

📄 Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT - lihat file LICENSE untuk detailnya.

🤝 Berkontribusi

Fork repositori
Buat cabang fitur Anda (git checkout -b feature/amazing-feature)
Komit perubahan Anda (git commit -m 'Add amazing feature')
Dorong ke cabang (git push origin feature/amazing-feature)
Buka Pull Request

📞 Dukungan

Masalah: GitHub Issues
Dukungan Bitnovo: https://www.bitnovo.com/
Protokol MCP: https://modelcontextprotocol.io/

🌟 Terkait

Model Context Protocol - Spesifikasi resmi MCP
Bitnovo Pay - Platform pembayaran mata uang kripto
Bitnovo Pay - Dokumentasi - Dokumentasi Resmi Bitnovo Pay
Bitnovo Pay - Documentación en Español - Documentación Oficial de Bitnovo Pay
MCP SDK - SDK MCP resmi untuk TypeScript