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

MCP-1C это MCP-сервер для платформы 1С:Предприятие. Он даёт AI-ассистенту доступ к метаданным конфигурации, коду на BSL и текстам запросов, проверяет безопасность и помогает генерировать код на BSL.

Установка

Скачайте готовый бинарник для вашей операционной системы со страницы Releases на GitHub, или установите одной командой:

# Linux / macOS
curl -fsSL https://feenlace.ru/install.sh | sh

# Windows (PowerShell)
irm https://feenlace.ru/install.ps1 | iex

При регистрации вы получите 14-дневный пробный период Профессиональной версии со всеми возможностями. Скачайте бинарник mcp-1c-pro в личном кабинете.

Расширенная: Бинарник mcp-1c-advanced доступен в личном кабинете после оформления подписки.

Профессиональная: Скачивание бинарника mcp-1c-pro доступно в личном кабинете после регистрации. 14 дней пробного периода, без привязки карты.

Подготовка скачанного файла на macOS и Linux

Скачанный по HTTP файл приходит без права на запуск: протокол передаёт содержимое, но не права доступа. В Finder такой файл выглядит обычным документом, а в терминале запуск заканчивается сообщением permission denied. Выставьте бит:

# macOS, Apple Silicon
chmod +x mcp-1c-pro-darwin-arm64

# Linux
chmod +x mcp-1c-pro-linux-amd64

На macOS этого мало, если файл скачан браузером: система приписывает ему атрибут com.apple.quarantine. У наших бинарников есть только служебная подпись, которую ставит сборщик Go, сертификата разработчика Apple нет, поэтому Gatekeeper файл с этим атрибутом не пропускает и завершает процесс сразу после запуска, без всякого вывода. Снимите атрибут:

xattr -d com.apple.quarantine mcp-1c-pro-darwin-arm64

Снимать карантин нужно не всегда. Через curl файл приходит без него, тогда хватает chmod +x. Посмотреть, что на файле висит, можно командой xattr mcp-1c-pro-darwin-arm64: нет строки com.apple.quarantine, значит и снимать нечего. Установка одной командой (install.sh выше) выставляет бит сама, доделывать за ней ничего не нужно.

На Linux карантина не существует, там достаточно chmod +x. На Windows не нужно ни того, ни другого: скачанный .exe запускается как есть.

Раз подписи Apple у файла нет, убедиться, что скачался именно наш файл, можно по контрольной сумме SHA-256. Она лежит рядом с каждой ссылкой в личном кабинете, а посчитать её у себя можно так:

# macOS
shasum -a 256 mcp-1c-pro-darwin-arm64

# Linux
sha256sum mcp-1c-pro-linux-amd64

Проверьте установку и узнайте версию бинарника: флаг --version выводит версию и атрибуцию BSL-LS.

mcp-1c-advanced --version

Активация триала: зарегистрируйтесь на feenlace.ru → подтвердите почту → получите 14 дней Профессиональной версии без привязки карты. Бинарник mcp-1c-pro лежит в личном кабинете на странице Скачать, ключ на странице Лицензии. Порядок активации описан ниже, в разделе Активация платной версии.

Активация платной версии

Расширенная и Профессиональная версии работают по лицензионному ключу. Пока ключ не активирован, бинарник запускается и отвечает на запросы, но платные инструменты в списке не появляются, и сообщения об этом нет. Поэтому первый признак неактивированной лицензии обычно не ошибка, а отсутствие ожидаемых инструментов у AI-клиента.

Ключ показан в личном кабинете на странице Лицензии: там же кнопка «Скопировать» и готовая команда активации. На странице «Скачать» лежит только бинарник, ключа там нет.

Как активировать

Активация это отдельная разовая команда, а не первый запуск сервера. Выполните её на той машине, где будет работать MCP-сервер. Пример ниже для Расширенной версии; в Профессиональной та же команда выполняется бинарником mcp-1c-pro:

mcp-1c-advanced --activate "MCP-XXXX-XXXX-XXXX-XXXX"

Вывод при успехе:

Activating license...
License activated successfully.

Команда сразу завершается и MCP-сервер не запускает. Запускайте сервер как обычно, ключ в его аргументах указывать не нужно: он уже сохранён на этой машине. Другого способа передать ключ нет, ни переменной окружения, ни файла настроек для него не предусмотрено.

Проверить результат можно командой mcp-1c-advanced --license-status: она печатает ключ, дату окончания и редакцию, а если действующей лицензии на машине нет, одну строку License: NOT ACTIVE. Пример вывода есть в разделе Лицензирование.

Одна машина на ключ

Ключ рассчитан на одну машину. Привязка возникает в момент активации и хранится в каталоге конфигурации, а не рядом с программой, поэтому обновление и переустановка самого бинарника её не сбрасывают.

Привязка теряется, когда машина перестаёт быть той же самой: удалён каталог конфигурации, система переустановлена начисто, либо сервер запущен в контейнере без постоянного тома. В этих случаях ключ нужно активировать заново. Пути каталога по операционным системам и правило для контейнеров собраны в разделе Развёртывание.

Перенос на другую машину

Если старая машина больше не запускается, действий на ней не требуется: активация на новой машине освобождает прежнюю сама, поэтому перенести ключ можно и тогда, когда старая машина сломалась, отдана или стёрта. Если активация на новой машине получила отказ, что делать, описано ниже.

Если старая машина ещё работает, остановите на ней сервер и не запускайте его там снова: сервер, запущенный на старой машине, может снова забрать ключ себе, и платные инструменты окажутся у него, а не на новой машине.

Команда mcp-1c-advanced --deactivate тоже освобождает машину. Она нужна в другом случае: вы уходите с этой машины и не собираетесь активировать ключ где-то ещё прямо сейчас. Для переноса она не нужна.

Если активация не прошла

Команда завершается ошибкой. Если ключ пустой, с версии 2.41.0 она отказывает сразу, по-русски, об этом ниже; в остальных случаях печатает строку, которая начинается словами Activation error. Причину называет её конец:

Activation error: license: activate: license: server returned 403: license expired

Что означает конец строки:

• license expired: срок действия ключа истёк. Продлите подписку в личном кабинете.
• key revoked: ключ отозван.
• license suspended: действие ключа приостановлено.
• invalid key: такого ключа нет. Сверьте его со страницей «Лицензии».
• invalid key format: ключ набран с ошибкой. Проверьте, что скопировали его целиком.
• rate limit exceeded (код 429): сервер лицензий временно отклоняет активацию, например после частых активаций. Подождите и повторите команду позже.

Ещё три отказа программа печатает по-русски. Первый, с версии 2.41.0, приходит без обращения к серверу лицензий: --activate получил пустую строку или одни пробельные символы, и команда завершается с кодом 2, даже если после пустого ключа стоит -h, --help или --version. Два других означают, что ключ в этот момент не удалось закрепить за этой машиной. Программа печатает одну из строк:

Ошибка: --activate получил пустой ключ, пустую строку или одни пробельные символы. Передайте ключ лицензии: --activate <ключ>.
Activation error: license: activate: лицензия уже активна на другой машине — деактивируйте её или обновите тариф
Activation error: license: activate: лицензия активна на другой машине — переключитесь на неё или обновите тариф

Первая строка значит, что ключа в команде нет: передайте его после --activate. Если вы увидели вторую или третью, проверьте, что на старой машине сервер остановлен, подождите и повторите команду. Если отказ повторяется и через час, напишите в поддержку.

Работа без интернета

Сама активация требует доступа в интернет. После неё платные возможности продолжают работать до 72 часов без связи, а затем выключаются до её восстановления.

Эта отсрочка рассчитана только на случай, когда связи нет. Если ключ отклонён по существу, например истёк его срок или он отозван, платные возможности выключаются сразу, без этих 72 часов.

Пробный ключ

Пробный ключ активируется той же командой и с тем же выводом, порядок активации у него тот же. Только у пробного ключа бывает отказ server returned 403: trial already active on this machine: на этой машине уже активирован другой пробный ключ. Если вы считаете это ошибкой, напишите в поддержку.

Данные синтакс-помощника (Расширенная / Профессиональная)

Инструмент code_search(action: "syntax_help") и проверка API check_bsl_api используют справочник встроенных функций, методов и типов платформы. В Расширенной и Профессиональной версиях он не встроен в бинарник, его нужно один раз собрать из синтакс-помощника вашей установленной платформы 1С. Команды ниже для Расширенной версии; в Профессиональной те же команды выполняются бинарником mcp-1c-pro:

# автоопределение установленной платформы (берётся самая новая версия)
mcp-1c-advanced --update-syntax

# явный путь к каталогу платформы, если автоопределение не сработало
mcp-1c-advanced --update-syntax --platform /opt/1cv8/8.3.27.1000

Команда разбирает файл shcntx_ru.hbk вашей платформы и сохраняет справочник в локальный кэш (~/.cache/mcp-1c/syntax/ на Linux, ~/Library/Caches/mcp-1c/syntax/ на macOS, %LocalAppData%\mcp-1c\syntax на Windows). После выполнения перезапустите MCP-сервер. Повторяйте команду после обновления платформы 1С.

Кэш общий для всех подключённых баз и хранит один набор данных. Если базы работают на разных версиях платформы, справочник соответствует той версии, на которую вы указали при последнем запуске (при автоопределении самой новой установленной). Для смешанного парка укажите нужную версию через --platform.

Если платформа 1С не установлена локально (например, вы работаете через EDT с удалённой базой), скопируйте файл shcntx_ru.hbk из каталога любой подходящей версии платформы (с сервера, с машины коллеги или из дистрибутива платформы) в отдельную папку и укажите её: mcp-1c-advanced --update-syntax --platform /путь/к/папке. Файл должен называться именно shcntx_ru.hbk. Синтаксис платформы в основном стабилен между минорными версиями 8.3.x, поэтому подойдёт файл близкой версии. После сборки кэша справочник работает без установленной локально платформы.

Подключение базы 1С

MCP-1C использует расширение конфигурации для доступа к базе. Следующие команды автоматической установки относятся к Открытой редакции (mcp-1c). В Расширенной и Профессиональной редакциях с v2.43.2 команда --install устанавливает или обновляет расширение на месте с сохранением его данных и настроек безопасности; см. порядок обновления.

# Файловая база - Windows
mcp-1c --install "C:\Users\Dev\InfoBases\ERP"

# Файловая база - Linux / macOS
mcp-1c --install ~/Documents/InfoBase

# Клиент-серверная база (MS SQL, PostgreSQL)
mcp-1c --install "srv-1c\buh_prod" --server --db-user Admin --db-password pass

Что произойдёт при установке Открытой редакции

1. В базу 1С загрузится расширение "MCP" (~50 КБ)
2. Расширение добавит HTTP-сервис для обмена данными с AI
3. Расширение Открытой версии работает только на чтение, не изменяет данные и конфигурацию
4. Отключение и удаление выполняются через Конфигуратор; это описание не относится к обновлению расширения с данными документов в платных редакциях

Затем опубликуйте HTTP-сервис 1С на веб-сервере. Это штатный способ на всех платформах: на Windows через Apache или IIS, на Linux через Apache или ibsrv.

Windows. Откройте базу в Конфигураторе от администратора, затем Администрирование → Публикация на веб-сервере. Укажите имя публикации (например base), на вкладке «HTTP-сервисы» включите опцию «Публиковать HTTP-сервисы расширений по умолчанию», нажмите «Опубликовать». Сервис MCPService поставляется в расширении и в общем списке сервисов не отображается, это штатное поведение платформы 1С.

Linux. Конфигуратор в Linux веб-серверы не видит, поэтому публикацию выполняют утилитой webinst из поставки платформы 1С.

На обеих платформах HTTP-сервис расширения должен попасть в файл публикации default.vrd. Способа два: опция «Публиковать HTTP-сервисы расширений по умолчанию», которая записывает в файл атрибут publishExtensionsByDefault="true", либо явный блок:

<httpServices>
    <service name="MCPService" rootUrl="mcp-1c" enable="true"
             reuseSessions="autouse" sessionMaxAge="20" poolSize="10" poolTimeout="5"/>
</httpServices>

При повторной публикации базы файл default.vrd перегенерируется, поэтому добавленный вручную блок после неё нужно вписать заново.

После публикации HTTP-сервис доступен по адресу, который включает алиас публикации, например http://localhost/base/hs/mcp-1c/version. Проверьте этот адрес и укажите его в параметре --base при настройке AI-клиента.

# Файловая база (локальный путь)
# Windows
mcp-1c --install "C:\Users\Dev\InfoBases\ERP"
# Linux / macOS
mcp-1c --install "/home/dev/bases/erp"

# Клиент-серверная база (удалённо через сеть)
mcp-1c --install "server-1c\erp" --server --db-user Admin --db-password pass

# Удалённая установка polling-клиента
mcp-1c-advanced --install-polling "server-1c\erp" --server --db-user Admin --db-password pass --poll-server-url http://mcp-host:9090 --poll-user myuser --poll-password mypassword12

Установка расширения

Расширение MCP_HTTPService связывает MCP-сервер с информационной базой. Файл mcp-1c-extension.cfe доступен в личном кабинете; он одинаков для всех операционных систем. В поставке v2.43.2 используется версия расширений 0.10.2.

Расширенная и Профессиональная редакции

С v2.43.2 --install устанавливает расширение или обновляет существующее на месте, сохраняя его данные и настройки безопасности. Сначала проверьте резервную копию вместе с данными расширений и выполните обновление на восстановленной копии. Используйте бинарник своей редакции:

mcp-1c-advanced --install "C:\test-base" --platform "C:\path\1cv8.exe"
# Для Профессиональной редакции:
mcp-1c-pro --install "C:\test-base" --platform "C:\path\1cv8.exe"

Для клиент-серверной базы передайте "server\base" вместо пути и добавьте --server; при необходимости укажите --db-user и --db-password. При ошибке загрузки или применения проверьте фактическое состояние расширения до повторной попытки. Установщик не удаляет расширение и не выполняет автоматический обход ошибки.

Успех установки не включает создание и изменение документов автоматически. Для этого администратор отдельно настраивает и проверяет инициализацию сеанса: настройка document. Обычные запросы и печать не требуют этой настройки записи.

Если исходники устанавливает администратор вручную, используйте следующий порядок.

Выгрузите точные исходники из своего бинарника в новый каталог:

mcp-1c-advanced --export-extension /new/path/MCP_HTTPService
# Для Профессиональной редакции:
mcp-1c-pro --export-extension /new/path/MCP_HTTPService

Команды — альтернативы для разных редакций; используйте одну, с отдельным новым каталогом. Экспорт не меняет базу и не перезаписывает существующие файлы.

Обновление выполняет администратор:

1. Сделайте и проверьте резервную копию базы вместе с данными расширений. Сначала выполните обновление на восстановленной копии.
2. Откройте существующее расширение MCP_HTTPService в Конфигураторе и загрузите выгруженные исходники командой «Загрузить конфигурацию из файлов» в это же расширение. При первой установке создайте его один раз, затем загрузите исходники. Не удаляйте и не создавайте заново установленное расширение: это теряет его данные и защиту от повторной записи той же операции.
3. Проверьте применимость, права и политику безопасности для своей базы. Инициализация сеанса требует явно согласованных настроек безопасного режима или профиля безопасности; коннектор их автоматически не меняет. Роль MCP_ОсновнаяРоль назначается штатным способом конфигурации вместе с нужными деловыми правами; затем откройте новый сеанс.
4. Обновите конфигурацию базы на месте. Проверьте версию расширения, прежнее чтение и печать, затем работу с одним знакомым черновиком на копии. При отказе применимости или безопасности остановитесь и сохраните работающее расширение и резервную копию.

Для фонового опроса в одной базе нужны оба расширения, MCP_HTTPService и MCP_Polling, версии 0.10.2. Обновляйте существующие расширения с сохранением данных. Порядок настройки опроса и его учётной записи описан в настройках сервера; HTTP-сервис 1С в этом режиме публиковать не нужно.

В поставляемых расширениях 0.10.2 задан режим совместимости 8.3.14. Перед установкой проверьте применимость расширений на копии своей базы. Не понижайте режим совместимости для принудительной установки.

Открытая редакция

Для Открытой редакции остаётся mcp-1c --install с примерами из подключения базы, либо установка её расширения через Конфигуратор. Не подменяйте расширение платной редакции расширением Открытой версии. После установки и обновления базы опубликуйте HTTP-сервис, если используете прямое HTTP-подключение.

Доступ по ролям

Вместе с расширением HTTP-сервиса в базу ставится роль MCP_ОсновнаяРоль, и расширение объявляет её своей основной ролью. Пользователь, у которого уже есть роли конфигурации, получает доступ к сервису без дополнительных действий, а пользователь, у которого нет ни одной роли, получает отказ. Роль называется одинаково в Открытой, Расширенной и Профессиональной версиях.

Выдать доступ за вас расширение не может: оно работает в безопасном режиме, а платформа отвергает администрирование пользователей информационной базы из расширения.

Каким способом выдавать доступ

Способ зависит от того, есть ли в конфигурации подсистема «Управление доступом».

Определить это можно заранее, не дожидаясь потери доступа: если в конфигурации есть справочник профилей групп доступа, значит есть и подсистема, потому что справочник входит в саму подсистему. Отсутствие справочника кладёт вас во второй случай.

Есть подсистема «Управление доступом». Выдавайте доступ через профиль групп доступа. Прямое назначение роли там не держится: пересчёт ролей пользователей стирает роль, назначенную напрямую, и заодно выключает свойство расширения, которым держится автоматический доступ. Пересчёт ролей это обычное административное действие, поэтому на прямое назначение в такой конфигурации полагаться нельзя.

Подсистемы «Управление доступом» нет. Назначайте роль MCP_ОсновнаяРоль напрямую: Администрирование → Пользователи, нужный пользователь, вкладка «Прочие».

Диагностика

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

Не полагайтесь на РольДоступна("MCP_ОсновнаяРоль"). Она может возвращать Нет даже пользователю, которому сервис отвечает 200: объявление основной роли даёт действующее право, не делая роль видимой для этой проверки. Проверяйте самим вызовом сервиса, например запросом к /hs/mcp-1c/version.

Если расширение ставилось с флагом --strip-default-roles, объявления основной роли в базе нет. Обычная учётная запись с ограниченными правами теряет доступ к сервису, пока роль ей не выдадут явно, а учётная запись администратора доступ сохраняет и разницы не замечает. Выдайте доступ той учётной записи, под которой настроено подключение MCP, способом из этого раздела.

Настройка AI-клиента

Добавьте MCP-1C в конфигурацию вашего AI-клиента.

Claude Desktop

Файл: %APPDATA%\Claude\claude_desktop_config.json (Windows) или ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "1c": {
      "command": "C:\\path\\to\\mcp-1c.exe",
      "args": ["--base", "http://localhost/base/hs/mcp-1c"]
    }
  }
}

Claude Code (CLI)

Файл: %USERPROFILE%\.claude.json (Windows) или ~/.claude.json (Linux/macOS). Альтернатива: команда claude mcp add.

{
  "mcpServers": {
    "1c": {
      "command": "C:\\path\\to\\mcp-1c-pro.exe",
      "args": ["--base", "http://localhost/base/hs/mcp-1c"]
    }
  }
}

Codex

Файл: %USERPROFILE%\.codex\config.toml (Windows) или ~/.codex/config.toml (Linux/macOS). Один и тот же файл настроек читают и Codex в терминале, и расширение Codex для IDE, поэтому сервер достаточно прописать один раз. Альтернатива: команда codex mcp add.

[mcp_servers.1c]
command = "C:\\path\\to\\mcp-1c.exe"
args = ["--base", "http://localhost/base/hs/mcp-1c"]

Cursor

Settings → MCP → Add Server

{
  "mcpServers": {
    "1c": {
      "command": "mcp-1c",
      "args": ["--base", "http://localhost/base/hs/mcp-1c"]
    }
  }
}

VS Code + Copilot

Файл: .vscode/mcp.json в корне проекта

{
  "servers": {
    "1c": {
      "command": "mcp-1c",
      "args": ["--base", "http://localhost/base/hs/mcp-1c"]
    }
  }
}

JetBrains IDE

Settings → Tools → AI Assistant → MCP Servers → Add

{
  "mcpServers": {
    "1c": {
      "command": "mcp-1c",
      "args": ["--base", "http://localhost/base/hs/mcp-1c"]
    }
  }
}

Первый запрос

Перезапустите AI-клиент и задайте вопрос о вашей конфигурации 1С. Примеры:

• «Покажи структуру конфигурации моей базы 1С»
• «Покажи все документы с реквизитом Организация»
• «Напиши запрос: остатки товаров по складам за текущий месяц»
• «Найди все использования регистра ТоварыНаСкладах»
• «Объясни модуль менеджера документа РеализацияТоваровУслуг»