0.1.4

1c-odata-mcp — универсальный MCP-сервер для 1С:Предприятие через OData

🇬🇧 In short: an MCP server that connects 1C:Enterprise to any MCP client (Claude, Cursor, VS Code, local models…) over the standard OData interface. Ask your accounting database in plain language (debtors, sales, taxes, cash flow, account turnover, document postings) and get the number back; opt-in, preview-gated write. Read-only by default. Run with npx -y 1c-odata-mcp. Works with any 1C where OData is published — cloud, SQL or local file base.

MCP-сервер (Model Context Protocol) для 1С:Предприятие через стандартный интерфейс OData. Позволяет работать с данными 1С на естественном языке из любого MCP-клиента — Claude, Cursor, VS Code, JetBrains, локальные модели (Ollama, LM Studio): спрашивать про контрагентов, документы, остатки, дебиторку, продажи, движение денег, ОСВ и проводки — а при явном включении ещё и создавать/изменять справочники и документы, проводить, регистрировать оплаты.

Если вы искали, как подключить 1С к нейросети / ИИ, готовый коннектор 1С OData или интеграцию 1С с Claude без программирования на стороне 1С — это оно.

• 🔌 Любой MCP-клиент: Claude Desktop и Claude Code, Cursor, VS Code (Continue/Cline), JetBrains — и локальные модели (Ollama, LM Studio)
• 🔐 Данные остаются у вас — сервер это локальный процесс, ходит только в вашу базу; с локальной моделью данные вообще не покидают сеть
• 🏢 Несколько информационных баз и организаций (юрлиц) одновременно
• 🔒 Только на чтение по умолчанию; запись — через двойной предохранитель и предпросмотр
• 🚀 Запуск одной командой: npx -y 1c-odata-mcp
• ⚙️ Ничего не ставится на стороне 1С — достаточно опубликованного OData (без COM-соединения, без доступа к SQL)

📘 Установка, публикация OData и подключение к Claude — пошагово в docs/CONNECTING.md. Здесь — про сам проект, возможности и ограничения.

---

Подойдёт под любой ваш вариант 1С

Коннектор общается с 1С только через OData. Если он включён — всё работает одинаково, как бы ни была развёрнута ваша база:

Тип хранилища (файловая или SQL) сам по себе сложность не меняет — важно лишь, поднята ли веб-публикация OData. Без включённого OData коннектор работать не может (он не использует COM и не лезет в SQL напрямую).

➡️ Пошаговая инструкция под каждый вариант — в docs/ODATA-SETUP.md. Адрес базы, учётка и подключение к Claude — в docs/CONNECTING.md.

---

Зачем это нужно

Сырой OData 1С — это сотни технических EntitySet с кириллическими именами (Catalog_Контрагенты, Document_РеализацияТоваровУслуг, AccumulationRegister_ТоварыНаСкладах) и GUID-ключами. Работать с этим из чата невозможно, а писать свой код под каждый отчёт долго.

Сервер прячет всю технику за понятными инструментами. Вы спрашиваете обычным языком — ИИ сам выбирает нужный инструмент, ходит в OData вашей базы и возвращает готовый ответ. Для руководителя — быстрый срез по бизнесу, для бухгалтера — рутина создания документов под контролем.

---

Возможности

Аналитика и чтение (по умолчанию):

• «Покажи дебиторку» → сальдо счёта 62 по контрагентам
• «История по контрагенту Ромашка» → все документы и взаиморасчёты
• «Остатки на складе» → количество и сумма по номенклатуре
• «Продажи за май», «движение денег за квартал» → обороты за период
• «ОСВ по 51 счёту за квартал», «какие проводки сделал этот документ» → оборотно-сальдовая ведомость и проводки из регистра бухгалтерии
• «Когда и кем заведён документ» → хронология документа для аудита
• поиск контрагентов и документов, карточки объектов, карта базы

Действия (при включённой записи, всегда с предпросмотром и подтверждением):

• «Заведи контрагента ООО Ромашка, ИНН …, телефон, email, расчётный счёт, директора»
• «Выстави счёт покупателю на 3 шт по 1000» → документ-черновик
• «Создай поступление от поставщика и реализацию покупателю», «проведи документ» → проводки формирует сама 1С
• «Оформи возврат от покупателя», «перемещение между складами», «оприходование / списание / инвентаризацию»
• «Проведи оплату», «списание с расчётного счёта», «приходный / расходный кассовый ордер»
• «Выпиши счёт-фактуру на реализацию», «акт об оказании услуг»
• «Сделай акт за июль как за июнь, поменяй период и количество» → копия прошлого документа со всеми реквизитами (содержание строк, счета учёта, банковский счёт) — так выставляют ежемесячные документы
• изменение реквизитов, строк документов; проведение и пометка на удаление

Читать можно документ любого типа (не только из списка выше) — «покажи возвраты за май», «найди перемещения» и т.п.

Полный перечень — в разделе Инструменты.

---

Пример диалога

Ниже — Claude Desktop, но диалог выглядит так же в любом MCP-клиенте.

Вы:     Кто из покупателей должен больше всего и на сколько?
Claude: (вызывает read.analytics.get_debtors) Топ дебиторов на сегодня:
        1. ООО «Ромашка» — 1 240 500 ₽
        2. ИП Иванов     —   318 000 ₽
        3. ООО «Берёзка» —    94 050 ₽
        Всего по счёту 62: 1 800 000 ₽.

Вы:     Заведи нового покупателя ООО «Восход», ИНН 7701234567, и выстави счёт на 10 шт по 2500.
Claude: (dry-run) Будут созданы:
        • Контрагент «ООО Восход» (ИНН 7701234567)
        • Счёт покупателю на 25 000 ₽ (10 × 2500)
        Подтвердить создание?
Вы:     Да
Claude: Готово: контрагент 00-000123, счёт № … (черновик, непроведён).

---

Быстрый старт

Впервые слышите про MCP? Это открытый протокол (Model Context Protocol), по которому ИИ-ассистент подключается к внешним инструментам. Здесь инструмент — ваша 1С: ассистент сам вызывает нужные функции и возвращает ответ. Ничего программировать не нужно — три шага ниже.

1. Опубликуйте OData в 1С и добавьте нужные объекты в «Состав» (подробно — docs/CONNECTING.md; если OData ещё не включён — docs/ODATA-SETUP.md).

2. Пропишите сервер в Claude Desktop (claude_desktop_config.json), подставив адрес и учётные данные:

   {
     "mcpServers": {
       "1c-odata": {
         "command": "npx",
         "args": ["-y", "1c-odata-mcp"],
         "env": {
           "ODATA_BASE_URL": "https://<сервер>/<база>/odata/standard.odata/",
           "ODATA_USERNAME": "...",
           "ODATA_PASSWORD": "..."
         }
       }
     }
   }
   

3. Перезапустите Claude Desktop (полностью) и спросите: «проверь соединение с 1С».

Полная настройка (адрес OData по площадкам, авторизация, запуск из исходников, Claude Code, диагностика ошибок) — в docs/CONNECTING.md.

---

Инструменты

60 инструментов (24 чтение/аналитика + 36 записей). У всех есть необязательный параметр database (какая база 1С — см. read.system.list_databases); у аналитических — ещё и organization (фильтр по юрлицу — см. read.system.list_organizations).

Чтение и аналитика:

Запись (✍️ требует включения, работает через dry-run → confirm=true):

Все инструменты проверены на живой базе 1С:Бухгалтерия предприятия 3.0.

Строки документов продажи и закупки принимают:

• content — реквизит «Содержание». Именно этот текст печатается в счёте и УПД («Услуги согласно приложению № 4 от 01.10.2025 г. к договору № 87 … за июль 2026 г.»). Сама 1С его не заполняет, так что для услуг задавайте явно.

• incomeAccount / expenseAccount — счета доходов и расходов кодом как в 1С (90.01.2, 90.02.2) или через Ref_Key. Их же можно задать на весь документ. Приоритет: строка → документ → регистр «Счета учёта номенклатуры» → 90.01.1 / 90.02.1. Счета применимы к продажным документам; счёт на оплату и поступление их не используют.

• orgBankAccount (счёт покупателю, реализация, акт) — банковский счёт организации, который печатается как реквизиты для оплаты: название, номер счёта или Ref_Key. Без указания берётся основной счёт организации.

write.document.add_document_line и remove_document_line пересобирают табличную часть, сохраняя реквизиты прежних строк — содержание, счета учёта, номенклатурную группу. update_document_lines заменяет строки целиком, поэтому там их задают заново. Строки пишутся в ту табличную часть, которая у документа заполнена: у акта услуг это «Услуги», у товарного документа — «Товары».

Ежемесячно повторяющиеся документы проще выставлять через write.document.copy_document: он берёт прошлый документ за образец и переносит все реквизиты, включая те, которых нет в схемах create_* — банковский счёт, ответственного, адрес доставки, доп. условия счёта. Меняются датой (date), реквизитами шапки (fields) и правками строк по номеру (lines). Счета расчётов копия берёт из исходного документа; если в fields сменить договор — по настройке нового договора.

Счета расчётов с контрагентом (62, 60, 76…) сервер берёт из настройки в 1С — регистра «Счета учёта расчётов с контрагентами»: сначала настройка договора, затем контрагента, организации и общая, с учётом валюты договора. Предпросмотр пишет, откуда взят счёт. Если регистр не опубликован в OData — стандартные 62.01/62.02 и 60.01/60.02.

Другой план счетов или виды операций. ODATA_ACCOUNTING_CONFIG и ODATA_DB_<ИМЯ>_ACCOUNTING_CONFIG задают план счетов, регистр бухгалтерии, коды счетов по умолчанию, аналитические префиксы и виды операций акта и оплаты. Без настройки сохраняются прежние значения БП РФ. Параметры, приоритеты и синтетический пример для Беларуси — Настройка учёта.

---

Безопасность

По умолчанию сервер работает только на чтение. Запись включается осознанно, через два независимых предохранителя:

1. Глобальный рубильник READ_ONLY=false.
2. Пер-базовый флаг ODATA_DB_<ИМЯ>_WRITABLE=true — базы без него остаются read-only даже при снятом глобальном. Так можно открыть запись в одну базу (напр. ИП) и защитить другие (напр. ООО).

Дополнительно при записи:

• dry-run по умолчанию — предпросмотр создания (и добавления/удаления строки документа) возвращает operationId; для записи передайте этот же id и те же аргументы вместе с confirm=true. При сетевой ошибке повторяйте подтверждение с тем же id, не запускайте новый предпросмотр;
• защита от неопределённого результата POST — локальный журнал сохраняет отпечаток запроса и результат. Повтор с тем же id и теми же аргументами вернёт сохранённый итог без второго POST; если соединение оборвалось и исход неизвестен, сервер заблокирует повтор и попросит сверить результат в 1С. Сверку делает write.operation.status: создаваемому объекту MCP сам назначает Ref_Key (UUIDv1, назначается при предпросмотре), поэтому повтор с той же ссылкой 1С отвергает на уровне уникального индекса, а после таймаута объект находится простым GET — и для документов, и для справочников. Правка строк документа сверяется по числу строк. По желанию в «Комментарий» документов можно дописывать видимую метку [op:<operationId>] (ODATA_WRITE_OPERATION_MARKER=true);
• договор по умолчанию — если contractRef не указан, а у контрагента ровно один подходящий договор (вид «с покупателем»/«с поставщиком», та же организация), он подставляется, как в форме 1С; иначе предпросмотр предупреждает: без договора 1С документ не проведёт;
• мягкое удаление — write.entity.mark_for_deletion ставит пометку (как в 1С); жёсткого DELETE нет;
• на стороне 1С в «Состав OData» включаются только нужные объекты, а у пользователя 1С должны быть права на запись.

Приватность данных. Сервер — локальный процесс на вашей машине: он ходит только в вашу базу 1С (по Basic-аутентификации) и отдаёт данные вашему MCP-клиенту. Никаких сторонних серверов проекта в цепочке нет. Если использовать локальную модель (Ollama, LM Studio), данные 1С вообще не покидают вашу сеть. Секреты — только из .env (или блока env конфига); пароль и заголовок авторизации в логи не попадают.

Журнал защиты от повторной записи хранится локально в ~/.1c-odata-mcp/write-journal (путь можно изменить через ODATA_WRITE_JOURNAL_DIR). В нём нет полного payload: сохраняются hash запроса, статус операции и ограниченная сводка результата (Ref_Key, Code, Number). Успешные, отклонённые и неподтверждённые предпросмотры удаляются через 90 дней; операции с неизвестным результатом хранятся год (раньше удалять нельзя: это разрешило бы опасный повтор). Раз в час чистятся и служебные файлы: зависшие .tmp и «осиротевшие» .lock. В Docker смонтируйте каталог журнала на том (ODATA_WRITE_JOURNAL_DIR), иначе защита теряется вместе с контейнером.

Как именно включить запись — docs/CONNECTING.md → Включение записи.

---

Несколько баз и несколько организаций

Это разные случаи:

• Несколько отдельных баз (разные OData-адреса) — один сервер обслуживает все; имя базы передаётся параметром database. Настройка в .env — см. docs/CONNECTING.md. Пример запроса: «сравни выручку buh и torg за май».
• Несколько организаций (юрлиц) в одной базе — отдельное подключение не нужно, работает фильтр organization. Пример: «остатки по организации Ромашка».

---

Ограничения

Стоит знать заранее:

• Нужен опубликованный OData. Сервер работает только через стандартный интерфейс OData 1С. Прямого доступа к SQL, COM-соединения или файлам сервера 1С он не использует и не требует.
• Объект должен быть в «Составе OData». Если объект не опубликован, инструмент вернёт вежливую подсказку с именем объекта и путём, куда его добавить. Публикуйте по мере необходимости.
• Целевая конфигурация — Бухгалтерия предприятия 3.0. Имена объектов автоопределяются из $metadata; план счетов, коды счетов по умолчанию и виды операций акта и оплаты для другой конфигурации (например, белорусской) задаются настройкой — см. Настройка учёта. На УТ/ERP и самописных конфигурациях чтение справочников/документов работает, а бухгалтерская аналитика и запись документов требуют проверки на копии базы.
• Документы создаются непроведёнными. Проводки формирует сама 1С при проведении (write.document.post_document или вручную) — сервер не «рисует» проводки напрямую.
• Регламентные операции не создаются. Закрытие месяца, амортизацию, расчёт себестоимости/НДС генерирует обработка «Закрытие месяца» своими алгоритмами — через OData их не запустить. Читать (read.document.search_documents/read.document.get_document) можно.
• Оплаты по договору (create_payment, create_bank_writeoff, ПКО/РКО). Счета расчётов и сумма взаиморасчётов ставятся в строки расшифровки платежа, шапка не заполняется — как в документах из 1С. Проводки по расчётам 1С формирует только при заполненной сумме взаиморасчётов — иначе проводит документ молча и без проводок. Для договора в рублях сервер заполняет её сам (= сумме платежа, курс 1); для договора в валюте или у.е. курс не угадывается — укажите его в 1С до проведения, предпросмотр об этом напомнит.
• ОГРН и прочие доп.реквизиты. Пишутся, только если в базе заведён соответствующий «дополнительный реквизит» (Администрирование → Дополнительные реквизиты). Иначе инструмент честно сообщает, что записать некуда.
• Адрес пишется текстом-представлением (не структурированный ФИАС-адрес).
• Пагинация и лимиты. Чтобы не выгружать тысячи строк, действует размер страницы и защитный максимум (ODATA_PAGE_SIZE / ODATA_MAX_ROWS); большие выборки усекаются с пометкой.

---

Как устроено

Локальный процесс на Node.js, общается с клиентом по протоколу MCP через stdio, а с 1С — по HTTP к OData (Basic-аутентификация). Стек: Node.js 20+, TypeScript (strict), официальный @modelcontextprotocol/sdk, нативный fetch, zod (валидация), pino (логи в stderr), fast-xml-parser (разбор $metadata).

Карта объектов строится автоматически из $metadata базы и кешируется; запросы собираются типобезопасным билдером. Несколько баз — у каждой свой клиент и свой кеш метаданных.

src/
  index.ts            точка входа
  context.ts          реестр баз: Connection (клиент + кеш $metadata) + ServerContext
  mcp/server.ts       инициализация MCP SDK, регистрация инструментов, stdio
  odata/              клиент, билдер запросов, пагинация, разбор $metadata, аналитика,
                      справочные резолверы, обработка ошибок, проверка публикации
  tools/              инструменты: meta, counterparties, documents, registers, cashflow,
                      sales, organization, write
  config/             конфигурация (.env, мультибаза) и маппинг имён/счетов
  types/              типы OData и доменные типы

---

Технические заметки

• + vs %20 в OData 1С. 1С не декодирует + в пробел внутри $filter (отвечает 400), поэтому query-string собирается через encodeURIComponent (пробел → %20), а не URLSearchParams.
• Счета учёта документов не подставляются автоматически через OData (это делает форма 1С при выборе номенклатуры) — сервер берёт их из регистра «Счета учёта номенклатуры», с откатом на стандартные коды плана счетов.
• Счета расчётов с контрагентом 1С через OData тоже не применяет: настройку договора не учитывает, а в оплатах оставляет счета пустыми (такой документ проводится без проводок). Сервер берёт их из регистра «Счета учёта расчётов с контрагентами» — самая частная запись по договору → контрагенту → организации с учётом вида расчётов (рубли / валюта / у.е.) — и пишет в предпросмотре, откуда взят счёт. Регистр не опубликован — стандартные 62.01/62.02, 60.01/60.02.
• Логи и stderr. stdout занят JSON-RPC, поэтому логи идут в stderr — но только в терминале. Под MCP-клиентом (когда stdin — pipe) логи пишутся в файл <tmpdir>/1c-odata-mcp/server.log, чтобы не сломать клиентов, трактующих любой вывод в stderr как фатальную ошибку. Вернуть логи в stderr: MCP_LOG_STDERR=1.
• Типизированные ответы. У всех 60 инструментов объявлен outputSchema — клиенты, поддерживающие structuredContent (не только текстовый JSON), могут типизировать ответ, не парсить текст.
• Имена инструментов. Трёхсегментный dot-notation: <read|write>.<категория>.<имя> (напр. read.analytics.get_debtors, write.sales.create_shipment) — группирует инструменты по категории и сразу видно, чтение это или запись.

---

Частые вопросы (FAQ)

MCP-клиент «висит» / запрос отваливается по таймауту. Если зависают даже мелкие вызовы (read.system.health_check, read.system.list_databases) — это почти всегда залипший процесс MCP (в Claude Desktop лечится полным перезапуском приложения, Cmd+Q и заново), а не база. Здоровый read.system.health_check отвечает за секунду.

Указываю другую базу, а она «недоступна» / отвечает только одна. Параметр database — это имя из read.system.list_databases (поле name, напр. ooo), а не «человеческое» название (label, напр. «ООО Ромашка»). Обращайтесь по имени.

Ответ пустой / «объектов 0». Не настроен Состав OData — добавьте нужные объекты в 1С (см. docs/ODATA-SETUP.md и docs/CONNECTING.md).

Работает медленно. Это латентность вашей 1С / хостинга, не Claude: годовые выборки на «шумных» базах бывают 10–30 секунд. Спрашивайте более узким периодом (квартал/месяц) — ответ приходит за секунды.

Нужен ли доступ к SQL базы или COM? Нет. Сервер использует только OData — ничего не ставится внутри 1С, в SQL напрямую он не лезет.

Безопасно ли пускать ИИ к боевой базе? По умолчанию — только чтение. Запись включается двумя независимыми флагами и работает через предпросмотр (dry-run) с подтверждением. Физического удаления нет (только пометка). См. Безопасность.

Какая 1С подойдёт? Любая, где включён OData — облако (Scloud/1cFresh), сервер с SQL или локальная файловая база. Пошагово под каждый случай — docs/ODATA-SETUP.md.

---

Благодарности

• @Alexsab — работа с документами в 0.4.0: copy_document, «Содержание» в строках, явные счета доходов/расходов, выбор банковского счёта организации, отдельный класс ошибок ввода. И, что ценнее всего, найденные на живой базе баги, которые юнит-тестами не ловятся: правка строк акта уходила мимо его табличной части, а подбор банковского счёта был сломан молча.
• @alexpostnik — защита записи от дублей в 0.5.0: идея и первая реализация журнала операций (operationId, issue #29, PR #30), а также правка числа инструментов в описании пакета (PR #28); настраиваемый план счетов и виды операций документов для конфигураций, отличных от БП РФ (PR #41).
• @AlexMarinenko — учётная аналитика в 0.6.0: ОСВ по счёту (get_account_turnover), проводки документа (get_document_postings) и хронология документа для аудита (get_document_history, PR #31).

Нашли ошибку или не хватает документа — issue и PR приветствуются. Особенно ценны находки на реальных базах: конфигурации 1С различаются, и то, что работает на одной, на другой отвечает 500-й.

---

Лицензия

MIT. Проект открытый — пользуйтесь, форкайте, присылайте issue и PR: https://github.com/evilbruce666/1c-odata-mcp.

⭐ Если коннектор оказался полезен — поставьте звезду на GitHub и расскажите в Discussions, какие вопросы задаёте своей 1С. Это лучшая мотивация развивать проект.