MCP-сервер 1С через COM (V83.COMConnector)

Внешний MCP-сервер на Python, который подключается к информационной базе 1С через COM-соединение (V83.COMConnector) и выполняет запросы на встроенном языке запросов. В отличие от подхода с расширением + HTTP-сервисами, здесь ничего не нужно ставить в саму базу — сервер сам открывает внешнее соединение.

⚠️ Работает только на Windows, где установлена платформа 1С:Предприятие.

Возможности (инструменты MCP)

Related MCP server: MSSQL MCP Server

Требования

• Windows + установленная 1С:Предприятие 8.3

• Python 3.10+

• Совпадение разрядности: 64-битный Python ↔ 64-битный comcntr.dll (32-битный ↔ 32-битный). Большинство современных установок — 64 бита.

Установка

cd "D:\Documents\разработка_1С\mcp-1c-com"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Регистрация COM-коннектора

Один раз, от имени администратора, зарегистрируйте comcntr.dll нужной версии:

regsvr32 "C:\Program Files\1cv8\8.3.25.1257\bin\comcntr.dll"

(путь к версии платформы — свой; берётся последняя установленная)

Конфигурация

Через переменные окружения. Скопируйте .env.example и задайте значения, либо выставьте переменные прямо в команде запуска / в .mcp.json (см. ниже).

Файловая база:

ONEC_FILE=C:\bases\acc
ONEC_USR=Администратор
ONEC_PWD=пароль

Серверная база:

ONEC_SRVR=server-1c
ONEC_REF=accounting
ONEC_USR=Администратор
ONEC_PWD=пароль

Готовая строка соединения целиком (имеет приоритет):

ONEC_CONNECTION_STRING=File="C:\bases\acc";Usr="Администратор";Pwd="pass"

Запуск вручную (проверка)

$env:ONEC_FILE = "C:\bases\acc"
$env:ONEC_USR  = "Администратор"
python server.py

Сервер работает по stdio-транспорту MCP. Для интерактивной отладки удобен mcp dev server.py (требует pip install "mcp[cli]").

Подключение к Claude Code

Добавьте сервер в .mcp.json проекта (пример — в mcp.json.example):

{
  "mcpServers": {
    "1c-com": {
      "command": "D:\\Documents\\разработка_1С\\mcp-1c-com\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Documents\\разработка_1С\\mcp-1c-com\\server.py"],
      "env": {
        "ONEC_FILE": "C:\\bases\\acc",
        "ONEC_USR": "Администратор",
        "ONEC_PWD": ""
      }
    }
  }
}

Либо командой:

claude mcp add 1c-com -- "<путь>\.venv\Scripts\python.exe" "<путь>\server.py"

Примеры использования

Запрос с параметром-датой:

{
  "query_text": "ВЫБРАТЬ Ссылка, ПРЕДСТАВЛЕНИЕ(Контрагент) КАК Контрагент, СуммаДокумента ИЗ Документ.РеализацияТоваровУслуг КАК Р ГДЕ Р.Дата >= &Дата УПОРЯДОЧИТЬ ПО Р.Дата",
  "params": { "Дата": "2026-01-01" },
  "limit": 100
}

Список справочников:

{ "kind": "catalogs" }

Описание объекта:

{ "full_name": "Справочник.Контрагенты" }

Вернёт реквизиты с типами (ссылочные — полным именем, напр. Справочник.ДоговорыКонтрагентов, Перечисление.ЮрФизЛицо; примитивные — Строка(12), Число(3)), табличные части и их реквизиты.

Выполнение кода / вычисление выражения (требует обработку-исполнитель, см. ниже):

{ "return_expression": "Справочники.Валюты.НайтиПоКоду(\"980\").Наименование" }

{ "code": "Док = Документы.РеализацияТоваровУслуг.НайтиПоНомеру(\"000001\"); Результат = Док.СуммаДокумента;" }

execute_script: обработка-исполнитель и «Защита от опасных действий»

Внешнее COM-соединение не отдаёт операторы Выполнить/Вычислить (это конструкции языка, а не методы глобального контекста). Поэтому execute_script исполняет код внутри модуля внешней обработки executor\mcpИсполнитель.epf, где эти операторы доступны как обычные операторы языка. Код может присвоить значение переменной Результат — оно будет возвращено.

Сборка обработки-исполнителя (если её нет в executor\):

powershell.exe -NoProfile -File "<skills>\epf-build\scripts\epf-build.ps1" `
  -InfoBasePath "C:\bases\acc" -UserName "Администратор" -Password "..." `
  -SourceFile "executor\src\mcpИсполнитель.xml" -OutputFile "executor\mcpИсполнитель.epf"

Предупреждение безопасности. Поскольку модуль использует Выполнить/Вычислить, платформа при загрузке обработки показывает «Предупреждение безопасности» (через COM это превращается в ошибку). Чтобы execute_script заработал, для пользователя ИБ нужно отключить «Защиту от опасных действий»:

• Конфигуратор → Администрирование → Пользователи → <пользователь> → снять флаг «Защита от опасных действий», либо

• один раз открыть executor\mcpИсполнитель.epf в толстом клиенте 1С и подтвердить с галкой «Запомнить выбор».

В старых режимах совместимости (напр. УТП 1.2) свойство ЗащитаОтОпасныхДействий пользователя ИБ через COM не записывается — отключайте флаг в Конфигураторе.

Остальные инструменты (execute_query, list_metadata, describe_object, connection_info) работают без этой настройки.

Особенности и ограничения

• Ссылки возвращаются как UUID. Чтобы получить читаемое представление, добавляйте в запрос ПРЕДСТАВЛЕНИЕ(Поле) КАК ПолеПредставление.

• «Пустая дата» 1С (0001-01-01) отдаётся как null.

• Весь COM-доступ идёт через один выделенный поток (COM-объекты 1С привязаны к апартаменту), поэтому запросы выполняются последовательно.

• Соединение ленивое и переиспользуется между вызовами.

• Параметры запроса поддерживают примитивы (число, строка, булево) и даты (ISO-строка). Передача ссылок параметром не поддерживается — фильтруйте по реквизитам/коду/наименованию внутри запроса.

• В describe_object ссылочные типы и Строка(N)/Число(d,f) определяются точно. В старых режимах совместимости (УТП 1.2 и т.п.) глобальный конструктор Тип() через COM недоступен, поэтому Дата, Булево и безразмерные строки показываются как примитив.

• execute_script требует обработку-исполнитель и отключённую «Защиту от опасных действий» (см. отдельный раздел выше).

Диагностика проблем

AttributeError: V83.COMConnector.Connect / Библиотека не зарегистрирована (TYPE_E_LIBNOTREGISTERED). Сам COM-класс зарегистрирован, но не зарегистрирована библиотека типов коннектора. 1С-коннектор — dual-интерфейс и резолвит имена методов (Connect) через typelib, поэтому без неё позднее связывание не находит ни одного метода. Лечится повторной регистрацией comcntr.dll от имени администратора (regsvr32 ставит и класс, и typelib):

Start-Process regsvr32 -ArgumentList '/s','"C:\Program Files\1cv8\<версия>\bin\comcntr.dll"' -Verb RunAs -Wait

Проверка, что typelib появилась: ключ HKCR\TypeLib\{98AC3B5B-5323-418F-8F07-E32F231D2393} должен существовать.

Класс не зарегистрирован (0x80040154) — не зарегистрирован сам класс (regsvr32 comcntr.dll) либо не совпадает разрядность Python и dll.

Несколько версий платформы установлено. V83.COMConnector указывает только на одну версию (последнюю зарегистрированную). Чтобы привязать к конкретной — выполните regsvr32 именно её comcntr.dll.

Структура

mcp-1c-com/
├── server.py        # MCP-сервер (FastMCP, stdio), определение инструментов
├── onec_com.py      # COM-подключение к 1С, запросы, описание объектов, исполнение кода
├── config.py        # сборка строки соединения из переменных окружения
├── executor/
│   ├── mcpИсполнитель.epf      # собранная обработка-исполнитель для execute_script
│   └── src/                    # её XML-исходники (модуль с ВыполнитьКод/ВычислитьВыражение)
├── requirements.txt
├── .env.example
└── mcp.json.example