Bitnovo Pay

официальный

MCP-сервер для интеграции Bitnovo Pay с AI-агентами. Предоставляет возможности приема криптовалютных платежей через API Bitnovo Pay. Включает создание платежей, проверку статуса, генерацию QR-кодов и управление вебхуками с поддержкой нескольких туннельных провайдеров (ngrok, zrok, manual).

GitHub

Что можно делать с Bitnovo Pay MCP?

Создание ончейн-криптоплатежа — Попросите ассистента сгенерировать адрес криптовалюты для определенной монеты и суммы в евро с помощью create_payment_onchain.
Создание ссылки для оплаты — Поручите ассистенту создать веб-ссылку для оплаты, где клиенты выбирают криптовалюту, через create_payment_link.
Проверка статуса платежа — Запросите текущее состояние и детали любого платежа по его идентификатору с помощью get_payment_status.
Список поддерживаемых валют — Получите доступные криптовалюты, опционально отфильтрованные по минимальной сумме в евро, используя list_currencies_catalog.
Генерация брендированного QR-кода для платежа — Создайте QR-код высокого разрешения для существующего платежа с помощью generate_payment_qr.
Просмотр вебхук-событий — Запросите уведомления о платежах в реальном времени, полученные от Bitnovo, через get_webhook_events.

Документация

MCP Bitnovo Pay

MCP-сервер для интеграции Bitnovo Pay с ИИ-агентами

Сервер Model Context Protocol (MCP), предоставляющий ИИ-агентам возможности криптовалютных платежей через интеграцию с API Bitnovo Pay. Этот сервер позволяет ИИ-моделям создавать платежи, проверять статус платежей, управлять 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: 100% бесплатный с открытым исходным кодом и постоянными URL
- 🏢 manual: Для серверов с публичным IP (N8N, Opal, VPS)
Поддержка множества LLM - Совместимость с:
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, Responses API, Agents SDK)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Сентябрь 2025, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
Высококачественные QR-коды (v1.1.0+):
- 📱 Разрешение по умолчанию 512px (увеличено с 300px) для современных дисплеев
- 🖨️ Поддержка до 2000px для профессиональной печати
- ✨ Четкие края с оптимизированными алгоритмами интерполяции
- 🎨 Пользовательский брендинг Bitnovo Pay с плавным масштабированием логотипа
Приватность по умолчанию - Конфиденциальные данные маскируются в логах, минимальное раскрытие данных
Безопасность - Принудительное использование HTTPS, проверка HMAC-подписи, безопасное обращение с секретами
Надежность - Встроенная логика повторных попыток, обработка тайм-аутов, работа без сохранения состояния

📋 Предварительные требования

Node.js 18+
Аккаунт Bitnovo Pay с идентификатором устройства и опциональным секретом устройства
Конфигурация окружения (см. руководства по настройке ниже)

⚡ Быстрый старт

1. Получите учетные данные Bitnovo

Зарегистрируйтесь на Bitnovo Pay
Получите идентификатор устройства из панели управления Bitnovo
(Опционально) Сгенерируйте секрет устройства для проверки подписи вебхуков

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. Протестируйте интеграцию

Спросите вашего ИИ-ассистента: "Создай платеж на 10 евро"

☁️ Облачное развертывание (НОВОЕ в v1.2.0)

MCP Bitnovo Pay теперь поддерживает удаленное развертывание на облачных платформах с режимом HTTP-транспорта. Это позволяет ИИ-платформам, таким как claude.ai, подключаться к вашему MCP-серверу удаленно.

Развертывание на Railway (Рекомендуется)

Быстрая настройка:

Нажмите «Deploy to Railway» или создайте новый проект
Установите переменные окружения:
- BITNOVO_DEVICE_ID - Ваш идентификатор устройства Bitnovo
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Разверните (Railway автоматически обнаружит Dockerfile)
Получите ваш публичный URL: https://your-app.up.railway.app

Подключение к claude.ai:

Добавьте сервер в Настройки → Model Context Protocol
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
BITNOVO_BASE_URL - URL API Bitnovo

Определение режима транспорта:

Если переменная окружения 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

Выберите вашу ИИ-платформу и следуйте конкретному руководству по настройке:

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), 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`	✅ Да	Конечная точка API Bitnovo	`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: QR URL платежного шлюза

Параметры размера QR (v1.1.0+):

По умолчанию: 512px (оптимизировано для современных дисплеев)
Диапазон: 100px - 2000px
Рекомендуемые размеры:
- 512px: Мобильные и веб-дисплеи
- 800-1200px: Стандартная печать
- 1600-2000px: Высококачественная печать (постеры, стенды)

Улучшения качества (v1.1.0):

✨ Четкие края с интерполяцией ядра nearest для QR-паттернов
🎯 Высококачественное масштабирование логотипа с ядром lanczos3
📦 Сжатие PNG уровня 6 с адаптивной фильтрацией
🖼️ Размер по умолчанию увеличен с 300px до 512px для лучшей четкости

Инструменты вебхуков

`get_webhook_events`

Запрос событий вебхуков, полученных в реальном времени от API Bitnovo Pay.

Доступно, когда: WEBHOOK_ENABLED=true

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

`get_webhook_url`

Получение публичного URL вебхука с инструкциями по настройке для панели Bitnovo.

Доступно, когда: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Диагностика состояния туннельного соединения (ngrok, zrok или manual).

Доступно, когда: 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
Предотвращение повторных атак - Кэширование nonce с TTL 5 минут
Конфиденциальность данных - Конфиденциальная информация маскируется в логах
Нет данных о курсах - Курсы обмена не раскрываются для предотвращения неточностей
Дизайн без состояния - Нет локального сохранения, запросы к API в реальном времени
Автопереподключение - Экспоненциальная задержка до 10 повторных попыток для туннелей
Мониторинг здоровья - Проверка соединения каждые 60 секунд

📄 Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для подробностей.

🤝 Участие в разработке

Форкните репозиторий
Создайте ветку функции (git checkout -b feature/amazing-feature)
Зафиксируйте изменения (git commit -m 'Add amazing feature')
Отправьте в ветку (git push origin feature/amazing-feature)
Откройте Pull Request

📞 Поддержка

Проблемы: GitHub Issues
Поддержка Bitnovo: https://www.bitnovo.com/
Протокол MCP: https://modelcontextprotocol.io/

🌟 Связанное

Model Context Protocol - Официальная спецификация MCP
Bitnovo Pay - Платформа криптовалютных платежей
Bitnovo Pay - Документация - Официальная документация Bitnovo Pay
Bitnovo Pay - Документация на испанском - Официальная документация Bitnovo Pay
MCP SDK - Официальный MCP SDK для TypeScript