invoicebox

Invoicebox MCP Server

Сервер Model Context Protocol для Инвойсбокса: ассистент выставляет счёт организации, ИП или физическому лицу, проверяет оплату, подтверждает отгрузку — а по ней формируются закрывающие документы, — и возвращает деньги. Всё по просьбе человека и с его подтверждением.

Права по умолчанию — только чтение. Ни одна операция с деньгами не выполняется в один вызов.

Быстрый старт на демо-магазине

Демонстрационный магазин опубликован в документации (авторизация), поэтому попробовать можно без своего договора. Он общий для всех читателей: пробные счета видны всем, поэтому реальные реквизиты и персональные данные в демо не вводите.

INVOICEBOX_API_TOKEN=b37c4c689295904ed21eee5d9a48d42e INVOICEBOX_MERCHANT_ID=ffffffff-ffff-ffff-ffff-ffffffffffff INVOICEBOX_ENV=demo npx -y @invoicebox/mcp-server

Записи включаются явно: INVOICEBOX_TOOLSETS=write добавляет счёт, отмену и отгрузку, refund — возврат. Токен можно не держать в переменной окружения: invoicebox-mcp-server login <токен> кладёт его в файл с правами только для владельца.

Пример конфигурации клиента MCP:

{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/[email protected]"],
      "env": {
        "INVOICEBOX_API_TOKEN": "b37c4c689295904ed21eee5d9a48d42e",
        "INVOICEBOX_MERCHANT_ID": "ffffffff-ffff-ffff-ffff-ffffffffffff",
        "INVOICEBOX_ENV": "demo",
        "INVOICEBOX_TOOLSETS": "read"
      }
    }
  }
}

Версию указывайте всегда: у платёжного инструмента latest означает, что набор инструментов может измениться между двумя запусками одного и того же диалога.

Инструменты

Инструмент	Что делает	Подтверждение
lookup_company_by_inn	Реквизиты организации или ИП по ИНН	нет
get_order	Счёт по идентификатору или по своему номеру	нет
find_orders	Срез по счетам: номер, статус, даты, суммы	нет
find_shipments	Что по заказу отгружено и в каком статусе	нет
create_order	Выставляет счёт, возвращает ссылку на оплату	двухфазное
cancel_order	Отменяет неоплаченный счёт	двухфазное
create_shipment	Подтверждает отгрузку, по ней идут акт, счёт-фактура и УПД	двухфазное
create_refund	Возвращает деньги полностью или по составу	двухфазное

Полный справочник с параметрами — https://docs.invoicebox.ru/mcp/tools/

Что важно знать до первого счёта

• Суммы — целые копейки строкой: "12200" это 122,00 ₽. Так модель не теряет копейку на числе с плавающей точкой.
• Цена — за единицу, сумма — за количество. amount и amount_wo_vat в позиции относятся к одной единице, total_amount и total_vat_amount — ко всему количеству.
• Все записи двухфазные. Первый вызов ничего не отправляет в API: возвращает сводку и одноразовый токен на 15 минут, привязанный к параметрам. Второй вызов с этим токеном исполняет операцию.
• Крупная сумма подтверждается отдельно. Выше порога (по умолчанию 100 000 ₽) сервер спрашивает человека, а не довольствуется числом, которое подставила модель.
• Повтор не создаёт дубль. Номер операции выводится из содержимого запроса; повтор того же вызова возвращает прежний результат.
• Покупатель — юрлицо, ИП или физлицо. В API типа два: legal (у ИП ИНН из 12 цифр и без КПП) и private.
• Закрывающие документы идут по отгрузке. Отдельного «сформировать УПД» нет: акт, ТОРГ-12, счёт-фактуру и УПД запускает create_shipment.

Настройки

Переменная	Обязательна	Назначение
INVOICEBOX_API_TOKEN	да, если нет файла токена	Токен из личного кабинета, вкладка «Интеграция (API)»
INVOICEBOX_ENV	да	demo или production; демо — магазин в тестовом режиме
INVOICEBOX_MERCHANT_ID	для операций магазина	Идентификатор магазина
INVOICEBOX_COUNTERPARTY_ID	для операций организации	Идентификатор организации
INVOICEBOX_TOOLSETS	нет	read по умолчанию, плюс write и refund
INVOICEBOX_STATE_DIR	нет	Каталог журнала и защиты от дублей; без него она живёт только в пределах запуска
INVOICEBOX_RATE_LIMIT	нет	Свой ограничитель, запросы/секунды; по умолчанию 60/30
INVOICEBOX_LIMITS	нет	Суточные потолки, JSON
INVOICEBOX_CONFIRM_THRESHOLD	нет	Порог суммы в копейках для отдельного подтверждения
INVOICEBOX_LOG_LEVEL	нет	error, warn, info, debug
INVOICEBOX_GRAYLOG_URL, INVOICEBOX_SENTRY_DSN	нет	Внешние приёмники журнала; выключены по умолчанию
INVOICEBOX_TOKEN_FILE	нет	Свой путь к файлу токена
INVOICEBOX_HTTP_PORT	нет	Задан — транспорт Streamable HTTP на этом порту, иначе stdio
INVOICEBOX_HTTP_HOST	нет	Адрес привязки HTTP; по умолчанию 127.0.0.1
INVOICEBOX_HTTP_ALLOWED_HOSTS, INVOICEBOX_HTTP_ALLOWED_ORIGINS	нет	Белые списки Host и Origin; по умолчанию наружу закрыто
INVOICEBOX_HTTP_SESSION_IDLE_MS, INVOICEBOX_HTTP_MAX_SESSIONS	нет	Срок жизни сессии (30 минут) и их потолок (200)

Полный список настроек — https://docs.invoicebox.ru/mcp/quickstart/

Расход контекста

Набор по умолчанию занимает около 1 100 токенов описаний, полный набор с возвратами — около 4 000. Выборка двадцати счетов стоит примерно 1 200 токенов в кратком формате и 2 900 в подробном. Ответы усекаются с явной пометкой, страница ограничена пятьюдесятью записями. Замеры и приёмы — https://docs.invoicebox.ru/mcp/tokens/

Разработка

npm ci
npm run typecheck
npm run lint
npm test
npm run build

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

• Раздел о сервере: https://docs.invoicebox.ru/mcp/
• Справочник инструментов: https://docs.invoicebox.ru/mcp/tools/
• Безопасность и подтверждения: https://docs.invoicebox.ru/mcp/security/
• Лимиты, ошибки и журнал: https://docs.invoicebox.ru/mcp/faq/
• Расход токенов: https://docs.invoicebox.ru/mcp/tokens/
• Ассистенты без MCP: https://docs.invoicebox.ru/mcp/functions/
• API Инвойсбокса: https://docs.invoicebox.ru/docs/api/

История изменений

Что менялось между версиями — в файле CHANGELOG.md внутри пакета (npm view @invoicebox/mcp-server versions покажет список выпусков). Версию в конфигурации указывайте явно: у платёжного инструмента latest означает, что набор инструментов может измениться между двумя запусками одного диалога.

Поддержка

Вопросы и доступ к бете — https://www.invoicebox.ru/ru/contacts