Skip to main content
Glama

elba-mcp

tests PyPI

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

Related MCP server: invox-mcp

Настройки

Переменная

Что задаёт

ELBA_API_KEY

ключ API, обязателен

ELBA_ORG_ID

организация, если по ключу их несколько; иначе берётся единственная

ELBA_STATE_DIR

каталог журнала счетов, по умолчанию ~/.local/state/elba-mcp

Инструменты

Инструмент

Что делает

elba_organizations

организации и банковские счета

elba_templates

шаблоны документов — template_id для счёта и акта

elba_find_contractor

поиск клиента по ИНН или названию

elba_lookup_inn

реквизиты организации или ИП по ИНН из ЕГРЮЛ/ЕГРИП ФНС (без ключа)

elba_get_contractor, elba_create_contractor

карточка клиента, новый клиент

elba_create_bill

счёт: позиции {name, price, quantity?, unit?}, без НДС по умолчанию; project — метка в журнале

elba_repeat_bill

новый счёт по образцу прошлого (ежемесячная поддержка)

elba_get_bill

счёт с суммой total и статусом оплаты

elba_track_bill

добавить в журнал счёт, выставленный не через сервер

elba_unpaid

неоплаченные счета из журнала со свежими статусами и общий долг

elba_payment_news

оплаты с прошлой проверки

elba_report

сводка: выставлено, оплачено, закрыто актами — всего, по проектам, за период

elba_act_from_bill

акт по счёту: позиции и клиент из счёта, основание «Счёт № от»

elba_create_act

акт с произвольными позициями

elba_upd_from_bill

УПД по счёту; счёт с НДС → со счётом-фактурой (статус 1), без НДС → статус 2

elba_create_upd

УПД с произвольными позициями; при with_nds ставка nds_rate обязательна

elba_document_link

публичная ссылка с печатью, подписью и QR-оплатой — её отправляют клиенту

elba_link_publish

снять ссылку с публикации (отменённый счёт) или вернуть

Банковский счёт подставляется сам, если открыт один; при нескольких открытых 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__<имя>, в других клиентах — из меню промптов. Каждый ведёт ассистента по шагам с проверками и ничего не отправляет клиенту сам: письма — только черновиками.

Промпт

Что делает

elba_invoice (клиент, работы, сумма)

найти или завести клиента, показать счёт на подтверждение, выставить, ссылка, черновик письма

elba_close_work (счёт, документ)

акт или УПД по счёту, ссылка, черновик письма

elba_remind_debtors (дней)

что оплачено, кто должен дольше N дней, черновики напоминаний

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

  • «Выстави ООО Ромашка счёт на 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.

Available Tools

19 tools
elba_act_from_billA

Акт по выставленному счёту: позиции, клиент и банковский счёт берутся из счёта, основание — «Счёт № от». act_date — ГГГГ-ММ-ДД, по умолчанию сегодня. Второй акт по тому же счёту — только с allow_duplicate=true.

Inputs: bill_id (required), number, act_date, template_id, +1 more.

elba_create_actB

Создать акт выполненных работ. items — как в elba_create_bill. Основание (например «Счёт», номер и дата счёта) — reason_name, reason_number, reason_date. bank_account_id — как в elba_create_bill. template_id — шаблон акта из elba_templates. Акт по выставленному счёту проще сделать elba_act_from_bill.

Inputs: items (required), contractor_id (required), number, act_date, +6 more.

elba_create_billA

Выставить счёт клиенту.

items — список {"name": "Название услуги", "price": 10000, "quantity": 1, "unit": "усл."}; quantity и unit необязательны (1 и «усл.»), при with_nds можно задать "nds_rate" (nds22 по умолчанию). bill_date — ГГГГ-ММ-ДД, по умолчанию сегодня; number — по умолчанию следующий номер Эльбы. template_id — шаблон из elba_templates; сверьте его текст: шаблон-оферта может описывать не тот договор. bank_account_id — по умолчанию единственный открытый счёт организации; при нескольких открытых обязателен. project — метка для журнала (например сайт клиента), по ней видно, за что счёт. Счёт записывается в журнал. Если тому же клиенту на ту же сумму счёт выставлен в пределах недели, создание останавливается; allow_duplicate=true — выставить всё равно. Возвращает счёт с номером, суммой и статусом.

Inputs: items (required), contractor_id (required), number, comment, +6 more.

elba_create_contractorB

Создать контрагента. Перед созданием проверьте elba_find_contractor по ИНН, чтобы не завести дубль.

Inputs: name (required), inn, kpp, ogrn, +5 more.

elba_create_updA

Создать УПД. items — как в elba_create_bill, плюс "type": "service" (по умолчанию) или "product". with_nds — УПД со счётом-фактурой (статус 1), без — только передаточный документ (статус 2). nds_rate — ставка при with_nds, обязательна: withoutNds, nds0, nds5, nds10, nds20, nds22 (у позиции можно переопределить "nds_rate"). УПД по выставленному счёту — elba_upd_from_bill.

Inputs: items (required), contractor_id (required), number, nds_rate, +6 more.

elba_find_contractorB

Найти контрагента в Эльбе по ИНН (надёжнее) и/или названию.

Inputs: inn, kpp, name. Returns: result

elba_get_billB

Счёт по id: номер, позиции, сумма и статус оплаты (notPaid, paid, partiallyPaid, rejected, overdue). total — null, если Эльба не вернула сумму хотя бы одной позиции. Счёт из журнала обновляется в журнале.

Inputs: bill_id (required).

elba_get_contractorC

Карточка контрагента с контактами.

Inputs: contractor_id (required).

elba_lookup_innA

Реквизиты организации или ИП по ИНН из ЕГРЮЛ/ЕГРИП ФНС (egrul.nalog.ru, без ключа): полное и краткое название, КПП, ОГРН, руководитель, дата регистрации, дата прекращения деятельности. Адреса поиск ФНС не отдаёт. Для elba_create_contractor: name — полное название, short_name — краткое. Сверьте с реквизитами от клиента; terminated — деятельность прекращена, счёт такому лицу выставлять нельзя.

Inputs: inn (required). Returns: result

elba_organizationsC

Организации, доступные по ключу, и их банковские счета.

Inputs: no named parameters.

elba_payment_newsA

Оплаты по счетам с прошлой проверки (лента новостей Эльбы): счёт, статус, сумма счёта и сколько пришло. Обновляет статусы в журнале. Первый вызов только ставит отметку в конец ленты — история не выводится.

Inputs: no named parameters.

elba_repeat_billA

Новый счёт по образцу прошлого: тот же клиент, позиции, НДС, банковский счёт, шаблон и проект. items — заменить позиции (формат elba_create_bill). Без items позиции копируются — проверьте названия: в них может остаться прошлый месяц. bill_date — по умолчанию сегодня. Дубли ловятся как в elba_create_bill.

Inputs: bill_id (required), items, number, comment, +2 more.

elba_reportA

Сводка по журналу счетов: сколько выставлено, оплачено и не оплачено, сколько счетов закрыто актом или УПД — всего и по проектам, плюс список счетов (по нему же счёт находят по номеру). Фильтры: project, contractor_id, date_from и date_to (ГГГГ-ММ-ДД, по дате счёта). Отменённые не считаются. Статусы — из журнала; счета, у которых лента оплат с журналом расходится, перечитываются из Эльбы. Оплаченная часть — из ленты. Суммы null, если какую-то узнать не удалось; errors — счета, что не перечитались. byProject — список, project null — счета без проекта.

Inputs: date_to, project, date_from, contractor_id.

elba_templatesA

Шаблоны документов (счета, акты, договоры) — id для template_id в elba_create_bill и elba_create_act.

Inputs: no named parameters. Returns: result

elba_track_billB

Добавить в журнал счёт, выставленный не через этот сервер (в Эльбе вручную или до появления журнала).

Inputs: bill_id (required), project.

elba_unpaidA

Неоплаченные счета из журнала со статусом из Эльбы и оплаченной частью из ленты оплат. Оплаченные и отменённые перечитываются, если лента расходится с журналом; recheck_all=true — все. Возвращает счета (номер, клиент, проект, сумма, оплачено, дней с даты счёта, ссылка) и общий долг; debt — null, если хоть одна сумма неизвестна или счёт не перечитался.

Inputs: recheck_all.

elba_upd_from_billA

УПД по выставленному счёту: позиции, клиент, банковский счёт и НДС берутся из счёта, основание — «Счёт № от». Счёт с НДС даёт УПД со счётом-фактурой (статус 1), без НДС — статус 2. product_type — service (по умолчанию) или product для всех позиций. Второй УПД по счёту — allow_duplicate=true.

Inputs: bill_id (required), number, upd_date, product_type, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: creation flows are split between from-scratch (elba_create_act/elba_create_upd) and from-bill variants, and contractor find/get/create are distinguishable. The only mild fuzziness is in the reporting cluster (elba_unpaid, elba_report, elba_payment_news, elba_get_bill), which all surface bill/payment status, though descriptions do differentiate list vs aggregate vs news feed vs single bill.

    Naming Consistency4/5

    All tools share a consistent elba_ prefix and snake_case, which makes the set easy to scan. Most are verb_noun (create_bill, act_from_bill, find_contractor), but several are bare nouns (organizations, templates, unpaid, report, payment_news), a minor deviation from the pattern.

    Tool Count4/5

    At 19 tools the set is slightly on the heavy side, but the domain (bills, acts, UPDs, contractors, links, orgs, templates, reporting, INN lookup) legitimately needs this breadth. Each tool maps to a real operation, with no obvious filler.

    Completeness3/5

    Creation and read paths are well covered, but mutation is thin: no update/delete for contractors, no update/cancel/delete for bills, and acts/UPDs can be created but not fetched or listed by id. The elba_link_publish description references cancelled bills, yet no cancellation tool exists, which is a notable lifecycle gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Create, send and track invoices from a conversation in Claude, ChatGPT or any MCP client that supports OAuth. Draft an invoice from one sentence or from last month's invoice for the same client, finalize it, email it to your client and send payment reminders for overdue ones. See revenue by month and by client, download PDFs and e-invoices (ZUGFeRD, XRechnung), and export DATEV packages for your tax advisor. Invoices follow the tax rules of 25 countries, including reverse charge and the small-business VAT exemption. New invoices are drafts, and nothing is emailed until you ask. Pay per invoice with no subscription: the first invoice is free.

      https://billstride.com/api/mcp
    • Invoice Simple MCP server for ChatGPT, Claude and any AI agent: create invoice, send invoice, create estimate, list unpaid invoices and mark invoice paid in your own Invoice Simple account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Invoice Simple yourself; Cotlet does not store your password and you need no Invoice Simple API key. About the official Invoice Simple API: Invoice Simple publishes no public API, API keys or developer documentation; its plans offer built-in payment integrations instead (checked 8 Nov 2026). It has no official MCP server. Setup and FAQ: https://cotlet.dev/integrations/invoice-simple-api-mcp-server

    • Bokio MCP server for ChatGPT, Claude and any AI agent: create invoice, send invoice, upload receipt, create journal entry and list unpaid invoices in your own Bokio account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Bokio yourself; Cotlet does not store your password and you need no Bokio API key. About the official Bokio API: Yes, Bokio has a public REST API for invoices, customers, journal entries, uploads and supplier invoices (checked 14 Oct 2026), but it depends on your price plan and on the kind of integration: a private integration token works for one company only, and a tool that serves several companies must be registered as a public integration with OAuth 2.0. Bokio publishes no MCP server of its own. Setup and FAQ: https://cotlet.dev/integrations/bokio-api-mcp-server

      https://cotlet.dev/mcp/v1/bokio
    • Fakturownia (InvoiceOcean) MCP server for ChatGPT, Claude and any AI agent: issue invoice, send invoice, mark invoice paid, add client and list unpaid invoices in your own Fakturownia (InvoiceOcean) account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Fakturownia (InvoiceOcean) yourself; Cotlet does not store your password and you need no Fakturownia (InvoiceOcean) API key. About the official Fakturownia (InvoiceOcean) API: Yes. Fakturownia has a documented REST API that creates invoices, clients and payments, sends invoices by email and sends them to KSeF (checked 14 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/fakturownia-api-mcp-server

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Elorus invoicing and accounting platform, enabling AI assistants to create invoices, manage contacts, and query financial data through natural language.
      43
      5
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Hosted MCP server that enables AI assistants to manage clients, invoices, and expenses via the Invox API, supporting actions like drafting, sending, cancelling, and marking invoices as paid, as well as logging expenses and updating client information.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Look up Russian companies by INN (tax ID) from Claude Desktop, Cursor or any MCP client: full company card, multi-year financials from official tax filings, bankruptcy and state-inspection history, trademarks and sanctions lists. Works without an API key — the anonymous free tier is enabled by default.
      5
      MIT