Invoicebox MCP Server

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

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

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

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

Code

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:

config.json

{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/mcp-server@0.2.1"],
      "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/

Разработка

Terminal

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