Bitnovo Pay

공식

Bitnovo Pay API를 통해 암호화폐 결제 기능을 제공하는 AI 에이전트 통합용 MCP 서버입니다. 결제 생성, 상태 확인, QR 코드 생성, 웹훅 관리 기능을 포함하며 여러 터널 제공자(ngrok, zrok, 수동)를 지원합니다.

GitHub

Bitnovo Pay MCP(으)로 무엇을 할 수 있나요?

온체인 암호화폐 결제 생성 — create_payment_onchain을 사용하여 특정 코인과 유로 금액에 대한 암호화폐 주소를 생성하도록 어시스턴트에 요청하세요.
공유 가능한 결제 링크 생성 — create_payment_link를 통해 고객이 암호화폐를 선택할 수 있는 웹 결제 URL을 어시스턴트가 생성하도록 하세요.
결제 상태 확인 — get_payment_status를 사용하여 식별자를 통해 모든 결제의 현재 상태와 세부 정보를 요청하세요.
지원되는 통화 목록 조회 — list_currencies_catalog를 사용하여 최소 유로 금액으로 선택적으로 필터링된 사용 가능한 암호화폐를 검색하세요.
브랜드 결제 QR 생성 — generate_payment_qr를 사용하여 기존 결제에 대한 고해상도 QR 코드를 생성하세요.
웹훅 이벤트 확인 — get_webhook_events를 통해 Bitnovo로부터 수신된 실시간 결제 알림을 조회하세요.

문서

MCP Bitnovo Pay

AI 에이전트와 Bitnovo Pay 통합을 위한 MCP 서버

Bitnovo Pay API 통합을 통해 AI 에이전트에 암호화폐 결제 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 AI 모델이 결제를 생성하고, 결제 상태를 확인하며, QR 코드를 관리하고, 암호화폐 카탈로그에 접근할 수 있도록 합니다.

🚀 기능

8개의 MCP 도구로 포괄적인 결제 관리:
- create_payment_onchain - 직접 결제용 암호화폐 주소 생성
- create_payment_link - 리디렉션 처리가 포함된 웹 결제 URL 생성
- get_payment_status - 상세 정보와 함께 결제 상태 조회
- list_currencies_catalog - 필터링 기능이 있는 지원 암호화폐 조회
- generate_payment_qr - 기존 결제에서 사용자 정의 QR 코드 생성
- get_webhook_events - 실시간으로 수신된 웹훅 이벤트 조회
- get_webhook_url - 구성 지침과 함께 공개 웹훅 URL 조회
- get_tunnel_status - 터널 연결 상태 진단
자동 웹훅 시스템 (3가지 터널 제공자):
- 🔗 ngrok: 무료 영구 URL (계정당 1개의 고정 도메인)
- 🌐 zrok: 영구 URL을 제공하는 100% 무료 오픈소스
- 🏢 수동: 공용 IP가 있는 서버용 (N8N, Opal, VPS)
다중 LLM 지원 - 호환 대상:
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, Responses API, Agents SDK)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro 2025년 9월, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
고품질 QR 코드 (v1.1.0+):
- 📱 최신 디스플레이를 위한 512px 기본 해상도 (300px에서 증가)
- 🖨️ 전문 인쇄를 위한 최대 2000px 지원
- ✨ 최적화된 보간 알고리즘으로 선명한 가장자리
- 🎨 부드러운 로고 스케일링이 적용된 사용자 정의 Bitnovo Pay 브랜딩
기본 개인정보 보호 - 로그에서 민감 데이터 마스킹, 최소한의 데이터 노출
보안 - HTTPS 강제, HMAC 서명 검증, 안전한 비밀 처리
신뢰성 - 내장 재시도 로직, 타임아웃 처리, 무상태 운영

📋 전제 조건

Node.js 18 이상
Bitnovo Pay 계정 (장치 ID 및 선택적 장치 비밀 키 포함)
환경 구성 (아래 설정 가이드 참조)

⚡ 빠른 시작

1. Bitnovo 자격 증명 얻기

Bitnovo Pay에서 가입하세요.
Bitnovo 대시보드에서 장치 ID를 얻으세요.
(선택 사항) 웹훅 서명 검증을 위한 장치 비밀 키를 생성하세요.

2. MCP 클라이언트 구성

MCP 클라이언트 구성 파일에 이 설정을 추가하세요:

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"
      }
    }
  }
}

OpenAI ChatGPT의 경우 (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. MCP 클라이언트 다시 시작

Claude Desktop, ChatGPT 또는 MCP 클라이언트를 다시 시작하여 서버를 로드하세요.

4. 통합 테스트

AI 어시스턴트에게 다음과 같이 요청하세요: "10유로 결제를 생성해 줘"

☁️ 클라우드 배포 (v1.2.0의 새로운 기능)

MCP Bitnovo Pay는 이제 HTTP 전송 모드를 통해 클라우드 플랫폼에서의 원격 배포를 지원합니다. 이를 통해 claude.ai와 같은 AI 플랫폼이 MCP 서버에 원격으로 연결할 수 있습니다.

Railway에 배포 (권장)

빠른 설정:

"Railway에 배포"를 클릭하거나 새 프로젝트를 만드세요.
환경 변수를 설정하세요:
- BITNOVO_DEVICE_ID - 귀하의 Bitnovo 장치 ID
- BITNOVO_BASE_URL - https://pos.bitnovo.com
배포하세요 (Railway가 Dockerfile을 자동 감지).
공개 URL을 얻으세요: https://your-app.up.railway.app

claude.ai에 연결:

설정 → 모델 컨텍스트 프로토콜에서 서버 추가
서버 URL: https://your-app.up.railway.app/mcp

📖 전체 가이드: 자세한 배포 지침, 문제 해결 및 구성은 RAILWAY.md를 참조하세요.

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

기타 플랫폼에 배포

이 서버는 Node.js와 Docker를 지원하는 모든 플랫폼에서 작동합니다:

Heroku: 환경 변수와 함께 Dockerfile 푸시
Fly.io: fly.toml 구성으로 배포
Google Cloud Run: Docker 컨테이너 배포
AWS ECS/Fargate: 작업 정의로 배포

필수 환경 변수:

PORT - HTTP 포트 (대부분의 플랫폼에서 자동 설정)
BITNOVO_DEVICE_ID - 귀하의 Bitnovo 장치 ID
BITNOVO_BASE_URL - Bitnovo API URL

전송 모드 감지:

PORT 환경 변수가 설정된 경우 → HTTP 모드 (원격 연결)
PORT가 없는 경우 → stdio 모드 (로컬 연결)

📦 설치 옵션

옵션 A: npx 사용 (권장)

설치가 필요 없습니다! npx 명령이 자동으로 최신 버전을 다운로드하여 실행합니다.

npx -y @bitnovopay/mcp-bitnovo-pay

장점:

✅ 항상 최신 버전 사용
✅ 수동 업데이트 불필요
✅ 로컬 설치 불필요
✅ 즉시 작동

옵션 B: 저장소 복제 (개발용)

코드를 수정해야 하는 기여자 또는 고급 사용자용:

# 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

장점:

✅ 소스 코드 완전 제어
✅ 변경 사항 수정 및 테스트 가능
✅ 프로젝트 기여에 이상적

🔧 LLM 플랫폼별 구성

AI 플랫폼을 선택하고 특정 설정 가이드를 따르세요:

Claude Desktop (Anthropic)

구성 파일 위치: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 가이드: Claude 설정 가이드

기본 구성:

{
  "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"
      }
    }
  }
}

웹훅 사용 시 (실시간 결제 알림용):

{
  "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

가이드: OpenAI 설정 가이드 지원 대상: GPT-5, GPT-4o, Responses API, Agents SDK

기본 구성:

{
  "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

가이드: Gemini 설정 가이드 지원 대상: Gemini 2.5 Flash/Pro (2025년 9월), CLI, FastMCP

기본 구성:

{
  "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_ID`	✅ 예	귀하의 Bitnovo Pay 장치 식별자	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ 예	Bitnovo API 엔드포인트	`https://pos.bitnovo.com` (프로덕션) `https://payments.pre-bnvo.com` (개발)
`BITNOVO_DEVICE_SECRET`	⚠️ 선택	웹훅 검증용 HMAC 비밀 키	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ 선택	웹훅 서버 활성화	`true` 또는 `false`
`TUNNEL_ENABLED`	⚠️ 선택	웹훅용 터널 자동 시작	`true` 또는 `false`
`TUNNEL_PROVIDER`	⚠️ 선택	터널 제공자	`ngrok`, `zrok`, 또는 `manual`

보안 참고: 자격 증명을 버전 관리에 커밋하지 마세요. 환경 변수 또는 안전한 비밀 관리를 사용하세요.

🛠️ MCP 도구 참조

결제 생성

`create_payment_onchain`

직접 거래를 위한 특정 주소로 암호화폐 결제를 생성합니다.

사용 시기: 사용자가 암호화폐(Bitcoin, ETH, USDC 등)를 지정한 경우

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

`create_payment_link`

고객이 암호화폐를 선택할 수 있는 웹 기반 결제 URL을 생성합니다.

사용 시기: 특정 암호화폐가 언급되지 않은 일반 결제 요청 (기본 옵션)

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

결제 관리

`get_payment_status`

상세 정보와 함께 현재 결제 상태를 조회합니다.

{
  "identifier": "payment_id_here"
}

상태 코드:

NR (준비 안 됨): 사전 결제 생성됨, 암호화폐 미할당
PE (보류 중): 고객 결제 대기 중
AC (완료 대기 중): 멤풀에서 암호화폐 감지됨
CO (완료됨): 블록체인에서 결제 확인됨
EX (만료됨): 결제 시간 제한 초과
CA (취소됨): 결제 취소됨
FA (실패): 거래 확인 실패

`list_currencies_catalog`

선택적 금액 기반 필터링으로 사용 가능한 암호화폐를 가져옵니다.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

고품질 출력으로 기존 결제에 대한 사용자 정의 QR 코드를 생성합니다.

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

QR 유형:

address: 암호화폐 주소만 (고객이 금액 수동 입력)
payment_uri: 주소 + 금액 포함 (권장)
both: 두 유형 모두 생성 (권장)
gateway_url: 결제 게이트웨이 URL의 QR

QR 크기 옵션 (v1.1.0+):

기본값: 512px (최신 디스플레이에 최적화)
범위: 100px - 2000px
권장 크기:
- 512px: 모바일 및 웹 디스플레이
- 800-1200px: 표준 인쇄
- 1600-2000px: 고품질 인쇄 (포스터, 스탠드)

품질 개선 사항 (v1.1.0):

✨ QR 패턴에 nearest 커널 보간을 사용한 선명한 가장자리
🎯 lanczos3 커널을 사용한 고품질 로고 스케일링
📦 적응형 필터링이 적용된 PNG 압축 레벨 6
🖼️ 더 나은 선명도를 위해 기본 크기가 300px에서 512px로 증가

웹훅 도구

`get_webhook_events`

Bitnovo Pay API에서 실시간으로 수신된 웹훅 이벤트를 조회합니다.

사용 가능 조건: WEBHOOK_ENABLED=true

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

`get_webhook_url`

Bitnovo 패널 구성 지침과 함께 공개 웹훅 URL을 가져옵니다.

사용 가능 조건: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

터널 연결 상태(ngrok, zrok 또는 수동)를 진단합니다.

사용 가능 조건: WEBHOOK_ENABLED=true

{}

📚 문서

API 도구 참조 - 모든 MCP 도구에 대한 상세 문서
사용 예시 - 실제 사용 예시
오류 처리 - 오류 코드 및 문제 해결
웹훅 시스템 - 웹훅 구성 및 터널 관리

🏗️ 개발

사용 가능한 스크립트

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

아키텍처

┌─────────────────┐
│   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/)    │
└─────────────────┘

이중 서버 아키텍처

MCP 서버는 두 개의 서버를 동시에 실행할 수 있습니다:

┌─────────────────────────────────────────────────────────┐
│             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)

🔒 보안

HTTPS 전용 - 모든 API 호출은 HTTPS 사용
HMAC 검증 - SHA-256을 사용한 웹훅 서명 확인
재생 공격 방지 - 5분 TTL의 논스 캐싱
데이터 개인정보 보호 - 민감 정보는 로그에서 마스킹됨
환율 데이터 없음 - 부정확성 방지를 위해 환율 미노출
무상태 설계 - 로컬 영속성 없음, 실시간 API 쿼리
자동 재연결 - 터널에 대해 최대 10회 재시도의 지수 백오프
상태 모니터링 - 60초마다 연결 확인

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🤝 기여

저장소를 포크하세요.
기능 브랜치를 만드세요 (git checkout -b feature/amazing-feature).
변경 사항을 커밋하세요 (git commit -m 'Add amazing feature').
브랜치에 푸시하세요 (git push origin feature/amazing-feature).
풀 리퀘스트를 여세요.

📞 지원

이슈: GitHub Issues
Bitnovo 지원: https://www.bitnovo.com/
MCP 프로토콜: https://modelcontextprotocol.io/

🌟 관련 자료

모델 컨텍스트 프로토콜 - 공식 MCP 사양
Bitnovo Pay - 암호화폐 결제 플랫폼
Bitnovo Pay - 문서 - Bitnovo Pay 공식 문서
Bitnovo Pay - 스페인어 문서 - Bitnovo Pay 공식 문서 (스페인어)
MCP SDK - TypeScript용 공식 MCP SDK