elba-mcp

MCP-сервер для Контур.Эльбы: ИИ-ассистент (Claude Code, Claude Desktop, Cursor и другие MCP-клиенты) находит или заводит клиента, выставляет счёт, акт или УПД, получает публичную ссылку на документ и следит за оплатами через публичный API Эльбы.

Неофициальный проект, с СКБ Контур не связан.

Установка

Нужен uv. Ключ API: Эльба → «Настройки и оплата» → «Настройки сервиса» → «API» → «Выпустить ключ».

Claude Code:

claude mcp add --scope user elba -e ELBA_API_KEY=ваш-ключ -- uvx elba-mcp

Claude Desktop и другие клиенты с JSON-настройкой:

{
  "mcpServers": {
    "elba": {
      "command": "uvx",
      "args": ["elba-mcp"],
      "env": { "ELBA_API_KEY": "ваш-ключ" }
    }
  }
}

Из исходников — uv run --script elba_mcp.py (зависимости uv ставит сам по метаданным скрипта); ключ тогда можно положить строкой ELBA_API_KEY=… в .env рядом с elba_mcp.py.

Работает на macOS и Linux. На Windows сервер запускается, но журнал счетов требует fcntl, поэтому создание счетов, актов и УПД там отказывает.

Настройки

Инструменты

Банковский счёт подставляется сам, если открыт один; при нескольких открытых bank_account_id обязателен. PDF через API Эльбы не скачать — клиент скачивает его по ссылке. Перед первым счётом сверьте текст шаблона: шаблон-оферта может описывать не тот договор, что ваши услуги.

Журнал счетов

API Эльбы не отдаёт список счетов, только счёт по id, поэтому сервер ведёт журнал сам: каждый счёт из elba_create_bill записывается туда с клиентом, суммой, проектом, ссылкой, актом и УПД. У каждой организации свой файл journal-<id организации>.json. В журнале данные клиентов — храните его как бухгалтерские документы.

• Защита от дублей: тому же клиенту на ту же сумму в пределах недели счёт не создаётся без allow_duplicate=true; второй акт или УПД по одному счёту — тоже. Проверка и создание идут под общей блокировкой, так что параллельные сессии ассистента дубль не создадут.
• Оплаты приходят из ленты новостей Эльбы. Первый вызов elba_payment_news только ставит отметку в конец ленты (у новостей нет дат, история не выводится), дальше — оплаты с прошлого вызова.
• elba_unpaid берёт оплаченную часть из всей ленты, статус — из Эльбы. Оплаченные и отменённые перечитываются, если лента с ними расходится; счёт, восстановленный из отменённых, — recheck_all=true. Долг null, если какую-то сумму узнать не удалось.
• Счета, выставленные в Эльбе вручную, в журнал не попадают сами — elba_track_bill.

Порядок работы

1. elba_find_contractor по ИНН; нет — elba_create_contractor.
2. elba_create_bill с template_id нужного шаблона и project, сверить номер и total.
3. elba_document_link → ссылку отправить клиенту.
4. Оплаты — elba_payment_news, должники — elba_unpaid.
5. После оплаты и сдачи работ — elba_act_from_bill или elba_upd_from_bill, затем ссылка на документ.

Без MCP, из шелла

uvx elba-mcp call elba_find_contractor args.json

args.json — аргументы инструмента, например {"inn": "<ИНН клиента>"}. Пригодится, когда сессия ассистента запущена до подключения сервера.

Разработка

Тесты — на моке API, без сети и без ключа, журнал во временном каталоге:

uv run pytest -q

Спецификация API: https://elba-api.kontur.ru/swagger/v1/swagger.json

Лицензия

MIT, см. LICENSE.