Invoicebox

ru.invoiceboxPublished by invoicebox.ruv0.2.1Updated Oct 25, 2026

MCP-сервер Инвойсбокса: счета, отгрузки и возвраты по просьбе человека

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Invoicebox MCP server lets an assistant look up company details, issue invoices, confirm shipments and process refunds in the Invoicebox payment service, with a

What you can do
Look up company or sole-trader details by tax ID, and read invoices and shipments by ID, number, status, dates or amounts. Issue an invoice and get a payment link, or cancel an unpaid invoice. Confirm a shipment, which triggers the closing documents (act, invoice, UPD). Refund money in full or by line item. All write operations are two-phase: the first call returns a summary and a short-lived token, the second call executes.
When to use it
Useful when you want an assistant to handle routine Invoicebox billing work — checking payment status, drafting invoices, confirming shipments or starting refunds — while a person confirms each money-related step. The demo store lets you try it without your own contract.
Requirements
Runs locally via npx (Node.js). Needs an Invoicebox API token (INVOICEBOX_API_TOKEN, or a token file created with the login command) and a merchant ID (INVOICEBOX_MERCHANT_ID). INVOICEBOX_ENV selects demo or production; demo is the default. Write and refund toolsets are off unless enabled via INVOICEBOX_TOOLSETS. Network access to the Invoicebox API.
Before you install
The API token grants whatever rights it has in your Invoicebox account; keep it out of shared configs. Write and refund tools move real money and create documents, so enable them deliberately and pin an explicit package version. The demo store is shared by all readers, so never enter real company details or personal data there. Large amounts need separate confirmation above a threshold.

Installation

In SourceWeft

  1. Open Invoicebox in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

json
{  "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 cinpm run typechecknpm run lintnpm testnpm run build

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

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

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

Поддержка

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

Source: README.md at commit 4b62bec

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.1LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.