@openaisdk/billing-mcp

MCP-сервер (stdio) для работы с Billing API из Cursor, Claude Desktop и других MCP-клиентов.

npm: @openaisdk/billing-mcp · бинарник: billing-catalog-mcp

Через tools можно читать и менять каталог (проекты, планы, цены, фичи, meters), проверять access / entitlements, смотреть платежи и создавать возвраты, а также inspect биллинг клиента: customer, subscriptions, usage summary, invoices, explain invoice, ledger postings. Всё от имени project-scoped API key.

Не входит в пакет: checkout, мутации подписок, usage ingestion, credits/adjustments, Test Clock / simulation, signup, секреты провайдера / webhook, generic REST-прокси. Для backend-интеграции приложения используйте @openaisdk/billing-sdk-node.

Установка

pnpm add -g @openaisdk/billing-mcp@latest
# или без глобальной установки — через npx в конфиге MCP

Требуется доступный Billing API и project-scoped integration key (кабинет → Интеграция).

Переменные окружения

Сервер читает .env из рабочей директории процесса (dotenv/config). В Cursor обычно задают env прямо в конфиге MCP.

| Переменная | Обязательно | Описание | | -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | BILLING_API_KEY | да | Project-scoped key (bsk_test_… / bsk_live_…) → Authorization: Bearer …. Без ключа процесс не стартует. | | BILLING_API_URL | нет | Base URL API без / в конце. Задавайте, если свой хост (иначе — localhost по умолчанию в коде). | | BILLING_PROJECT_ID | да для catalog tools | UUID проекта этого ключа. billing_list_projects ключу недоступен. |

Tenant и project для auth берутся из ключа; x-tenant-id не нужен. Ключ пишет каталог своего проекта (ADR-035). reset-catalog — только non-production. Создание проекта, merchant, webhooks, promo grant — human owner/admin. Sibling test/live — отдельный ключ.

Те же имена, что у @openaisdk/billing-sdk-node. Ключи в репозиторий не коммитьте.

Подключение клиента

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "billing-catalog": {
      "command": "npx",
      "args": ["-y", "@openaisdk/billing-mcp@latest"],
      "env": {
        "BILLING_API_KEY": "<project-scoped-key>",
        "BILLING_API_URL": "https://api.example.com",
        "BILLING_PROJECT_ID": "<project-uuid>"
      }
    }
  }
}

BILLING_API_URL опционален — укажите, если API на своём хосте.

Claude Desktop

В claude_desktop_config.json — тот же блок mcpServers / command / args / env.

После правки конфига перезапустите MCP в клиенте.

Tools

Ответы — JSON в content MCP. Ошибки: Error: ….

Почти везде для catalog tools нужен projectId в аргументах или BILLING_PROJECT_ID. Исключения без projectId: billing_get_payment и все tools раздела Customer billing inspection (scope из Bearer key). billing_list_projects ключу недоступен.

Проекты

| Tool | Назначение | | ----------------------- | --------------------------------------------------------------------------------------------- | | billing_list_projects | Список проектов tenant — human session, ключ получает 403. Задавайте BILLING_PROJECT_ID | | billing_get_project | Детали проекта — тоже human session, 403 у ключа |

Планы (products)

| Tool | Назначение | | --------------------- | -------------------------------------------------------------------------------- | | billing_list_plans | Список планов | | billing_get_plan | План по productId (prod_…) | | billing_create_plan | Создать: code, name; опц. description, isPublic, isActive, sortOrder | | billing_update_plan | PATCH: productId + поля кроме code |

Цены

| Tool | Назначение | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | billing_list_prices | Список цен | | billing_get_price | Цена по priceId | | billing_create_price | Создать: code, amountMinor, interval (month|year) и productId или productCode; опц. currency (по умолчанию RUB), intervalCount, trialDays, isActive | | billing_update_price | PATCH: priceId + поля цены; план сменить нельзя |

Фичи и привязки к плану

| Tool | Назначение | | ------------------------------- | ----------------------------------------------------------------------------------------------------- | | billing_list_features | Список фич | | billing_create_feature | Создать: code, name, kind (boolean|limit); опц. meterId, enforcement, sortOrder | | billing_update_feature | PATCH: featureId; code не меняется | | billing_list_product_features | Привязки к плану (productId или productCode) | | billing_create_plan_feature | Привязать: featureId + план; для limit — limitValue (null = безлимит) | | billing_update_plan_feature | PATCH привязки: planFeatureId + план | | billing_delete_plan_feature | Удалить привязку: только при confirm=true. Предпочтительнее soft-path: update с enabled=false |

Meters

| Tool | Назначение | | ----------------------- | ------------------------------------------------------------------- | | billing_list_meters | Список meters | | billing_create_meter | Создать: code, name, unit, aggregationType (sum|count) | | billing_archive_meter | Архивировать: meterId |

Access и entitlements

| Tool | Назначение | | --------------------------- | --------------------------------------------------- | | billing_get_access | Снимок access: customerAccountId (cus_…) | | billing_list_entitlements | Grants по customer account | | billing_check_entitlement | Проверка фичи: customerAccountId, feature (код) |

Платежи и возвраты

| Tool | Назначение | | ------------------------------- | ------------------------------------------------------------------------------------------------------- | | billing_list_payments | Список платежей; опц. limit, offset | | billing_get_payment | Платёж по paymentId | | billing_list_payment_refunds | Возвраты по платежу | | billing_get_payment_refund | Один возврат: paymentId, refundId | | billing_create_payment_refund | Создать возврат: paymentId, amountMinor; опц. reason, allocation, idempotencyKey (иначе UUID) |

Customer billing inspection

Read-only поверхность над public /v1 API. Не даёт менять subscription, invoice или ledger.

| Tool | Назначение | | ------------------------------------- | ----------------------------------------------------------------------------------------------------- | | billing_get_customer | Customer по customerAccountId (cus_…) | | billing_list_customer_subscriptions | Подписки клиента: customer; опц. status, limit, startingAfter | | billing_get_subscription | Подписка по subscriptionId (sub_…) | | billing_get_usage_summary | Агрегированный usage: meterId (код), customer, startTime, endTime; опц. valueGroupingWindow | | billing_list_customer_invoices | Счета клиента: customer; опц. limit, startingAfter | | billing_get_invoice | Счёт по invoiceId (inv_…) | | billing_explain_invoice | Детерминированное объяснение суммы из stored snapshot (не LLM, не пересчёт) | | billing_get_ledger_entries | Проводки: обязателен customer или invoice или payment; опц. период и пагинация |

Отдельный billing_get_customer_billing_overview не добавлен: агент собирает картину за 3–4 вызова из tools выше; толстый overview потребовал бы второй API и раздувал payload.

Примеры запросов агенту

Покажи планы и цены проекта. Ничего не создавай.

Создай план code=team, name=Team, затем цену team_monthly на 99000 копеек / month.

Проверь entitlement feature=ai_clustering для cus_….

Сделай возврат 10000 копеек по платежу <paymentId> с reason=partial.

Покажи текущее состояние биллинга клиента cus_...

Какой тариф и какие лимиты сейчас действуют для cus_...?

Сколько AI-токенов использовал cus_... в текущем расчётном периоде?

Объясни, почему invoice inv_... имеет именно такую сумму.

Покажи финансовые проводки, связанные с invoice inv_...

Ошибки и ограничения

• Нет BILLING_API_KEY — процесс падает при старте.
• HTTP-ошибки API: Error: HTTP <status>: <body>.
• amountMinor — минорные единицы (копейки для RUB).
• productCode резолвится в prod_… через список планов; при опечатке — «план не найден».
• billing_delete_plan_feature: нужен строго boolean confirm=true (строка "true" не подходит).
• Нет tools для создания/изменения/отмены подписок, checkout, usage ingestion, credits, invoice adjustment, Test Clock, secrets и integration key lifecycle.
• Customer billing inspection — только чтение; explain/ledger не меняют финансовые документы.
• Customer-wide ledger фильтр опирается на metadata.customerAccountId у проводок; для проводок по конкретному счёту используйте invoice=inv_….
• billing_list_projects / billing_get_project — human owner/admin, не ключ.
• Create/archive meters и refunds по-прежнему требуют tenant-роль; catalog write ключа их не открывает.

Чеклист

• [ ] Задан действующий BILLING_API_KEY
• [ ] При своём хосте задан BILLING_API_URL, API доступен
• [ ] Задан BILLING_PROJECT_ID проекта этого ключа
• [ ] Read-only tools каталога (billing_list_plans) работают
• [ ] Без confirm=true delete plan-feature отклоняется
• [ ] После смены mcp.json MCP перезапущен

Лицензия

MIT