1c-odata-mcp — подключение 1С:Предприятие к ИИ (Claude) через OData

🇬🇧 In short: an MCP server that connects 1C:Enterprise to Claude over its standard OData interface. Ask your accounting database in plain language (debtors, sales, taxes, cash flow) 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С на естественном языке прямо из ИИ-ассистента Claude (и любого MCP-клиента): спрашивать про контрагентов, документы, остатки, дебиторку, продажи и движение денег — а при явном включении ещё и создавать/изменять справочники и документы, проводить, регистрировать оплаты.

Если вы искали, как подключить 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 по контрагентам
• «История по контрагенту Ромашка» → все документы и взаиморасчёты
• «Остатки на складе» → количество и сумма по номенклатуре
• «Продажи за май», «движение денег за квартал» → обороты за период
• поиск контрагентов и документов, карточки объектов, карта базы

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

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

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

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

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

Вы:     Кто из покупателей должен больше всего и на сколько?
Claude: (вызывает 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), подставив адрес и учётные данные:

   copy

   {
     "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.

Инструменты

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

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

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

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

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

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

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

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

• dry-run по умолчанию — инструмент сначала показывает, что создаст, и пишет только при confirm=true;
• мягкое удаление — mark_for_deletion ставит пометку (как в 1С); жёсткого DELETE нет;
• на стороне 1С в «Состав OData» включаются только нужные объекты, а у пользователя 1С должны быть права на запись.

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

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

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

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

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

Ограничения

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

• Нужен опубликованный OData. Сервер работает только через стандартный интерфейс OData 1С. Прямого доступа к SQL, COM-соединения или файлам сервера 1С он не использует и не требует.
• Объект должен быть в «Составе OData». Если объект не опубликован, инструмент вернёт вежливую подсказку с именем объекта и путём, куда его добавить. Публикуйте по мере необходимости.
• Целевая конфигурация — Бухгалтерия предприятия 3.0. Имена объектов автоопределяются из $metadata, но аналитика (дебиторка/остатки) и счета учёта документов рассчитаны на план счетов БП 3.0. На УТ/ERP и самописных конфигурациях чтение справочников/документов работает, а бухгалтерская аналитика может потребовать доработки.
• Документы создаются непроведёнными. Проводки формирует сама 1С при проведении (post_document или вручную) — сервер не «рисует» проводки напрямую.
• Регламентные операции не создаются. Закрытие месяца, амортизацию, расчёт себестоимости/НДС генерирует обработка «Закрытие месяца» своими алгоритмами — через OData их не запустить. Читать (search_documents/get_document) можно.
• Оплата (create_payment). Документ создаётся и проводится, но бухгалтерские проводки Дт 51 Кт 62 формируются только если у банковского счёта организации настроен счёт учёта (51) — это настройка в 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С при выборе номенклатуры) — сервер берёт их из регистра «Счета учёта номенклатуры», с откатом на стандартные коды плана счетов.
• Логи и stderr. stdout занят JSON-RPC, поэтому логи идут в stderr — но только в терминале. Под MCP-клиентом (когда stdin — pipe) логи пишутся в файл <tmpdir>/1c-odata-mcp/server.log, чтобы не сломать клиентов, трактующих любой вывод в stderr как фатальную ошибку. Вернуть логи в stderr: MCP_LOG_STDERR=1.

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

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

Указываю другую базу, а она «недоступна» / отвечает только одна. Параметр database — это имя из 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.

Лицензия

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

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