1C Odata MCP

MCP-сервер для 1С:Предприятие через OData: данные 1С на естественном языке из Claude. Чтение по умолчанию, запись по флагу. Работает с любой 1С, где включён OData — облако (Scloud/1cFresh), сервер с SQL или локальная файловая база.

GitHub

Documentation

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

Диалог с Claude: на вопрос «кто из покупателей должен больше всего» приходит список должников и итог из 1С

🇬🇧 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) 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. Если он включён — всё работает одинаково, как бы ни была развёрнута ваша база:

Ваша 1С	Что нужно, чтобы заработало	Сложность
Облако / хостинг (Scloud, 1cFresh, аренда 1С)	OData включает провайдер — галочкой в кабинете или по заявке	🟢 низкая
Сервер с SQL (PostgreSQL / MS SQL)	опубликовать базу на Apache/IIS + включить OData	🟡 средняя
Локальная файловая база (`.1CD`)	то же + выдать веб-серверу права на папку базы	🟡 средняя
Нет веб-сервера / доступа к конфигуратору	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 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С: ассистент сам вызывает нужные функции и возвращает ответ. Ничего программировать не нужно — три шага ниже.

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

Пропишите сервер в 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": "..."
      }
    }
  }
}

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

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

Инструменты

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

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

Инструмент	Что делает
`read.system.list_databases` / `read.system.list_organizations`	Список баз / организаций (для параметров `database` / `organization`)
`read.organization.get_organization_card`	Карточка организации: ИНН/КПП/ОГРН, ОКВЭД, налоговый орган, адреса, банковский счёт, директор и главный бухгалтер
`read.schema.list_entities` / `read.schema.describe_entity`	Карта объектов базы и поля конкретного объекта (из `$metadata`)
`read.counterparty.find_counterparty` / `read.counterparty.get_counterparty`	Поиск контрагента (по названию/ИНН) и его карточка
`read.document.search_documents` / `read.document.get_document`	Поиск документов и документ с табличной частью
`read.analytics.get_debtors` / `read.analytics.get_inventory`	Дебиторка (сч. 62) / остатки товаров (сч. 41/10/43), можно на дату в прошлом (`asOf`)
`read.analytics.get_sales` / `read.analytics.get_cashflow`	Продажи за период / движение денег (банк + касса)
`read.analytics.get_sales_breakdown` / `read.analytics.get_purchases_breakdown`	Продажи/закупки с разбивкой по контрагенту, месяцу, договору, категории (ИП/ЮрЛицо/…)
`read.analytics.get_payments_breakdown`	Приход/расход по виду операции, месяцу, контрагенту, статье ДДС — «сколько заплатили ИП за год», «проценты по депозиту»
`read.analytics.get_taxes_paid`	Уплаченные налоги и взносы за период, с разбивкой по виду налога
`read.analytics.get_deal_history`	Хронология движений по сделке (код в назначении платежа) или договору
`read.counterparty.get_customer_history` / `read.counterparty.get_supplier_history`	История взаиморасчётов с покупателем / поставщиком
`read.system.health_check`	Проверка соединения и авторизации

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

Инструмент	Что делает
`write.counterparty.create_counterparty`	Контрагент (+ телефон/email/адрес/ОГРН)
`write.counterparty.create_bank_account` / `write.counterparty.create_contact_person`	Расчётный счёт (банк по БИК) / контактное лицо (директор)
`write.catalog.create_nomenclature`	Номенклатура (папка, артикул, признак услуги)
`write.catalog.create_contract`	Договор (вид, номер, валюта, тип цен, руководитель контрагента)
`write.sales.create_invoice` / `write.purchase.create_supplier_invoice`	Счёт покупателю / счёт на оплату поставщика (непроведёнными)
`write.purchase.create_purchase` / `write.sales.create_shipment`	Поступление от поставщика / реализация покупателю
`write.warehouse.create_return_from_customer` / `write.warehouse.create_return_to_supplier`	Возврат товаров от покупателя / поставщику
`write.warehouse.create_transfer`	Перемещение товаров между складами
`write.warehouse.create_surplus` / `write.warehouse.create_writeoff`	Оприходование / списание товаров
`write.warehouse.create_inventory`	Инвентаризация товаров на складе
`write.sales.create_act`	Реализация услуг (акт)
`write.sales.create_services_act`	Акт об оказании услуг (доходы/расходы по номенклатурной группе)
`write.money.create_payment` / `write.money.create_payout_order`	Оплата от покупателя (поступление на р/с) / платёжное поручение
`write.money.create_bank_writeoff`	Списание с расчётного счёта (исходящий платёж, вид операции обязателен)
`write.money.create_cash_receipt` / `write.money.create_cash_payment`	Приходный / расходный кассовый ордер (ПКО / РКО)
`write.sales.create_issued_invoice` / `write.purchase.create_received_invoice`	Счёт-фактура выданный / полученный (на основании реализации / поступления)
`write.entity.create_folder` / `write.entity.move_to_folder`	Папка (группа) справочника / перемещение в папку
`write.counterparty.update_counterparty` / `write.catalog.update_nomenclature` / `write.entity.update_entity`	Изменение реквизитов (PATCH)
`write.document.update_document_lines` / `write.document.add_document_line` / `write.document.remove_document_line`	Редактирование строк документа
`write.document.post_document`	Провести / отменить проведение (1С формирует проводки)
`write.entity.mark_for_deletion`	Пометить на удаление / снять пометку (мягкое удаление)

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

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

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

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

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

dry-run по умолчанию — инструмент сначала показывает, что создаст, и пишет только при confirm=true;
мягкое удаление — write.entity.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С при проведении (write.document.post_document или вручную) — сервер не «рисует» проводки напрямую.
Регламентные операции не создаются. Закрытие месяца, амортизацию, расчёт себестоимости/НДС генерирует обработка «Закрытие месяца» своими алгоритмами — через OData их не запустить. Читать (read.document.search_documents/read.document.get_document) можно.
Оплата (write.money.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.
Типизированные ответы. У всех 55 инструментов объявлен 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.

Лицензия

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

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