Как подключить Paddle Billing к Gemini через MCP

💡 Без установки? Используйте cloud.anythingmcp.com напрямую. Войдите, нажмите Connectors → Paddle Billing, вставьте учётные данные, создайте MCP API key, и готово. Без Docker, без git clone, без локального сервера.

Paddle Billing + Gemini

Paddle Billing, merchant of record для продажи софта: товары, цены и скидки, клиенты с адресами и компаниями, подписки с предпросмотром, паузой и возобновлением, транзакции и PDF-счета, возвраты и кредиты, CSV-отчёты, метрики выручки и MRR, события и webhook-уведомления. Live или sandbox; отмена подписки и разовые списания отключены при установке.

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

Полные инструкции по настройке встроены в коннектор (видны в магазине при выборе коннектора). Требуемые переменные окружения:

PADDLE_API_KEY, PADDLE_API_URL

Шаг 1 — Получите учётные данные

Настройка занимает около 2 минут. Нужен аккаунт Paddle Billing, live или sandbox, и право создавать в нём API-ключи.

1. В Paddle откройте Developer tools, Authentication, API keys и создайте ключ.
2. Выдайте ключу права, которые нужны инструментам: чтение для товаров, цен, скидок, клиентов, адресов, компаний, подписок, транзакций, корректировок, отчётов, уведомлений и событий, а запись только для тех сущностей, которые ИИ должен менять. Вызов по сущности без права отвечает 403.
3. Вставьте ключ в PADDLE_API_KEY без кавычек и без префикса Bearer. Live-ключи начинаются с pdl_live_apikey_, sandbox-ключи с pdl_sdbx_apikey_.
4. Укажите в PADDLE_API_URL https://api.paddle.com для live-аккаунта или https://sandbox-api.paddle.com для sandbox-аккаунта, без косой черты в конце. Ключ работает только на хосте своего окружения.
5. Установите коннектор и запустите paddle_list_event_types: ему не нужны id, и он подтверждает ключ.

Коннектор передаёт ключ как bearer-токен и фиксирует версию API 1 заголовком Paddle-Version. Он работает только с Paddle Billing, не с Paddle Classic.

Что он читает: каталог, то есть товары с их ценами, цены с периодом оплаты, пробным периодом, переопределениями по странам и ограничениями количества, а также скидки с кодом, типом, лимитом использования, числом использований и сроком действия; клиентов (поиск по e-mail или тексту) с их адресами, компаниями (название, регистрационный номер, номер плательщика НДС, контакты для счетов) и кредитными балансами по валютам; подписки со статусом, позициями, расчётным периодом, датой следующего списания и запланированной паузой, отменой или возобновлением, при желании с предпросмотром следующего списания; транзакции (checkout, продления, счета) с суммами, разбивкой налогов, платежами с кодами ошибок и номером счёта, с фильтрами по клиенту, подписке, статусу, номеру счёта или дате выставления либо создания; корректировки (возвраты, кредиты, чарджбэки) со статусом одобрения; ранее запрошенные отчёты; чистую выручку, MRR и число активных подписчиков по дням, как на дашборде Paddle; события за последние 90 дней; адресатов уведомлений, отправленные webhook- и e-mail-уведомления и каждую попытку доставки с HTTP-статусом и ответом вашего эндпоинта.

Что он записывает: создаёт и изменяет товары, цены, скидки, клиентов, адреса и компании (архивируются через status: archived; в Paddle ничего не удаляется); изменяет подписки (смена тарифа или количества с proration_billing_mode, скидка, дата списания, адрес, способ оплаты), ставит их на паузу, возобновляет и активирует подписку на пробном периоде, при этом первый платёж списывается сразу; создаёт и изменяет транзакции: checkout, который оплачивает клиент (его checkout.url), или счёт с collection_mode: manual и status: billed; делает возврат или кредит по транзакции через paddle_create_adjustment (возвраты имеют статус pending_approval, пока Paddle их не проверит); создаёт ссылки на клиентский портал, заказывает CSV-отчёты и повторно отправляет уведомления. Запланированная пауза или отмена снимается через paddle_update_subscription с scheduled_change: null.

Сначала предпросмотр: paddle_preview_subscription_update, paddle_preview_transaction и paddle_preview_prices рассчитывают списания, налоги и суммы, ничего не сохраняя. Перед сменой тарифа ИИ запускает предпросмотр, показывает вам немедленное списание и ждёт вашего «да». На live-хосте выставленные транзакции, изменения подписок, активации и возвраты двигают настоящие деньги.

Отключено при установке: paddle_cancel_subscription (немедленная отмена окончательна) и paddle_create_subscription_charge (разовое списание с сохранённого способа оплаты). Администратор workspace включает их осознанно.

Форматы данных: в каждом ответе есть data и meta.request_id. У id есть префикс: pro_ товар, pri_ цена, dsc_ скидка, ctm_ клиент, add_ адрес, biz_ компания, sub_ подписка, txn_ транзакция, adj_ корректировка, rep_ отчёт, ntf_ уведомление. Суммы передаются строками в минимальных единицах валюты: "1999" в USD это 19,99, у JPY нет дробной части. Итоги транзакции лежат в details.totals (subtotal, discount, tax, total, grand_total), по позициям в details.line_items. Даты в формате RFC 3339 в UTC. Фильтры с несколькими значениями перечисляются через запятую.

Файлы и отчёты: paddle_get_transaction_invoice и paddle_get_adjustment_credit_note возвращают временную ссылку на PDF, которая истекает примерно через час. Отчёты готовятся в фоне: paddle_create_report, затем paddle_get_report, пока статус не станет ready, затем paddle_get_report_csv для ссылки на CSV, которая истекает через несколько минут. Типы отчётов: транзакции, позиции транзакций, корректировки, позиции корректировок, скидки, товары и цены, баланс, сверка выплат, checkout и подписки.

Постраничная выдача: инструменты списков возвращают до per_page элементов (по умолчанию 50, максимум 200). Пока meta.pagination.has_more равно true, ИИ берёт значение after из URL в meta.pagination.next и передаёт его как after.

Ограничения: Paddle допускает 240 запросов в минуту с одного IP-адреса, сверх этого отвечает 429.

Частые ошибки: ошибки приходят как error.type, error.code и error.detail, а error.errors перечисляет неверные поля. 401 означает неверный ключ или ключ другого окружения (sandbox-ключ на live-хосте или наоборот). 403 forbidden означает, что у ключа нет права на эту сущность: отредактируйте ключ в Paddle и добавьте его. 404 entity_not_found означает неверный id или id из другого окружения.

Коннектор ничего не удаляет, не создаёт и не меняет адресатов уведомлений и не работает с аккаунтами Paddle Classic.

Шаг 2 — Установите адаптер

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Шаг 3 — Добавьте коннектор в Gemini

URL вашего сервера: в AnythingMCP откройте MCP Servers → сервер, на котором находится этот коннектор, и скопируйте его URL (https://cloud.anythingmcp.com/mcp/…). Используйте его везде, где в этом руководстве указано YOUR_SERVER_ID.

Gemini CLI читает MCP-серверы из ~/.gemini/settings.json (в Windows: %USERPROFILE%\.gemini\settings.json). Добавь:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Создай MCP API-ключ в AnythingMCP в разделе MCP Servers → твой сервер → API keys и вставь его вместо YOUR_MCP_API_KEY.
2. Сохрани файл и перезапусти gemini.
3. Выполни /mcp в Gemini CLI (или gemini mcp list в терминале): anythingmcp должен отображаться как подключённый.
4. Начинай писать промпты: Gemini CLI теперь может вызывать инструменты Paddle Billing.

Доступные инструменты

Примеры запросов

• «Какими были чистая выручка и MRR по дням в прошлом месяце и сколько активных подписчиков было у нас в конце месяца?»
• «Найди клиентку [email protected] и покажи её подписки со статусом, позициями и датой следующего списания.»
• «Сделай предпросмотр перевода этой подписки на годовую цену с пропорциональным расчётом и покажи немедленное списание, прежде чем что-то менять.»
• «Выведи транзакции этой недели со статусом past_due: клиент, сумма и ошибка платежа.»
• «Какие webhook-уведомления не доставлены за последние 24 часа и что ответил наш эндпоинт?»

FAQ

Где Gemini CLI ищет MCP-серверы? В ~/.gemini/settings.json для твоего пользователя или в .gemini/settings.json внутри проекта. gemini mcp list показывает каждый сервер и статус подключения.

Следующие шаги

• Страница коннектора
• Подключить к Claude
• Подключить к ChatGPT
• Подключить к Cursor
• Подключить к Meta Muse
• Подключить к Microsoft Copilot