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; тесты в CI идут на всех трёх.

Настройки

Инструменты

Банковский счёт подставляется сам, если открыт один; при нескольких открытых 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.

Сценарии

Готовые сценарии — MCP-промпты: в Claude Code они вызываются как /mcp__elba__<имя>, в других клиентах — из меню промптов. Каждый ведёт ассистента по шагам с проверками и ничего не отправляет клиенту сам: письма — только черновиками.

Без промптов — обычной фразой:

• «Выстави ООО Ромашка счёт на 40 000 за доработку сайта, проект romashka.ru, и подготовь письмо».
• «Что оплатили? Кто мне должен?» — elba_payment_news, elba_unpaid.
• «Счёт 114 оплачен — сделай акт и пришли ссылку» — elba_act_from_bill, elba_document_link.
• «Повтори счёт за поддержку на ноябрь» — elba_repeat_bill с новым названием позиции.
• «Сколько выставлено и оплачено по romashka.ru в этом году?» — elba_report.
• «Счёт 120 отменили — сними ссылку» — elba_link_publish.

Удобнее всего работать из проекта клиента: ассистент там знает, какие работы сделаны, и точнее пишет позиции счёта и письмо.

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

uvx elba-mcp call elba_find_contractor args.json

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

Разработка

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

uv run pytest -q

Релиз: поднять __version__ в elba_mcp.py, закоммитить и отправить тег vX.Y.Z — GitHub Actions прогонит тесты и опубликует пакет на PyPI через Trusted Publishing.

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

Лицензия

MIT, см. LICENSE.