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

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

Проверьте установку и узнайте версию бинарника:

mcp-1c-advanced --version    # выводит версию и атрибуцию BSL-LS

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

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

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

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

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

Активация это отдельная разовая команда, а не первый запуск сервера. Выполните её на той машине, где будет работать MCP-сервер:

mcp-1c-advanced --activate "MCP-XXXX-XXXX-XXXX-XXXX"    # или mcp-1c-pro

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

Activating license...
License activated successfully.

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

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

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

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

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

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

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

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

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

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

Команда завершается ошибкой и печатает строку, которая начинается словами Activation error. Причину называет её конец:

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

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

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

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

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

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

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

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

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

Пробный ключ

Пробный ключ активируется той же командой и с тем же выводом. Отличий в самом порядке активации между пробным и оплаченным ключом нет.

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

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

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

# явный путь к каталогу платформы, если автоопределение не сработало
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 использует расширение конфигурации для чтения метаданных. Установите его автоматически:

# Файловая база - 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. Расширенная версия добавляет возможность выполнения кода через sandbox с подтверждением и аудит-логом
5. Расширение можно отключить или удалить в любой момент через Конфигуратор

Затем опубликуйте 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

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

Расширение это файл конфигурации 1С mcp-1c-extension.cfe. Оно связывает сервер MCP с вашей информационной базой и одинаково для всех операционных систем. Скачайте файл в личном кабинете на вкладке «Скачать».

Установить расширение в базу можно двумя способами.

Через Конфигуратор. Откройте базу в Конфигураторе, выберите «Конфигурация» → «Расширения конфигурации», нажмите «Добавить» и загрузите скачанный файл mcp-1c-extension.cfe.

Командой установки. Команда --install загружает расширение в указанную базу автоматически:

mcp-1c-advanced --install "C:\Users\Dev\InfoBases\ERP"     # или mcp-1c-pro

Форматы пути к файловой базе и строки подключения к серверной базе описаны выше в разделе Подключение базы 1С.

После установки 1С выполнит штатное обновление конфигурации базы данных. Файл расширения один для всех операционных систем, отдельные сборки под Windows, Linux или macOS не нужны.

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

Вместе с расширением 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С»
• «Покажи все документы с реквизитом Организация»
• «Напиши запрос: остатки товаров по складам за текущий месяц»
• «Найди все использования регистра ТоварыНаСкладах»
• «Объясни модуль менеджера документа РеализацияТоваровУслуг»