Kontur.Elba MCP

MCP-сервер для управления данными в Контур.Эльбе через официальный Elba Public API.

Сервер работает локально по stdio, передаёт API-ключ только в заголовке X-Kontur-ApiKey и разрешает запросы только к операциям из приложенной OpenAPI-схемы.

Возможности

• получение доступных организаций;

• создание и просмотр банковских счетов;

• создание, поиск и просмотр контрагентов;

• создание, обновление, поиск и просмотр товаров;

• работа с новостями по документам и подписками;

• создание счетов, актов, накладных и УПД;

• проверка долгих операций;

• создание, изменение, получение и удаление публичных ссылок;

• получение шаблонов документов;

• просмотр параметров каждой операции прямо через MCP.

Полный контракт API сохранён в openapi.json.

Related MCP server: mindbox-mcp

1. Получите API-ключ

1. Откройте Эльбу.

2. Нажмите «Настройки и оплата» → «Настройки сервиса».

3. Откройте вкладку API.

4. Нажмите «Выпустить ключ».

5. Скопируйте ключ и сохраните его в менеджере секретов: повторно Эльба его не покажет.

Не добавляйте ключ в код, .env в Git или переписку. Если ключ раскрыт, отзовите его в Эльбе и выпустите новый.

2. Установите и соберите сервер

Требуется Node.js 20 или новее.

git clone https://github.com/apo100l/elba-kontur-mcp.git
cd elba-kontur-mcp
npm install
npm run build

После публикации можно установить пакет глобально без клонирования:

npm install --global elba-kontur-mcp

В конфигурации MCP в этом случае используйте команду elba-kontur-mcp без args.

3. Подключите MCP-клиент

Укажите абсолютный путь к dist/index.js и передайте ключ через окружение.

Codex

Добавьте сервер в ~/.codex/config.toml:

[mcp_servers.kontur_elba]
command = "node"
args = ["/absolute/path/to/elba-kontur-mcp/dist/index.js"]

[mcp_servers.kontur_elba.env]
ELBA_API_KEY = "ваш-api-ключ"

После изменения конфигурации перезапустите Codex.

Claude Desktop

Добавьте сервер в claude_desktop_config.json:

{
  "mcpServers": {
    "kontur-elba": {
      "command": "node",
      "args": ["/absolute/path/to/elba-kontur-mcp/dist/index.js"],
      "env": {
        "ELBA_API_KEY": "ваш-api-ключ"
      }
    }
  }
}

Перезапустите Claude Desktop.

Другой MCP-клиент

Запускаемая команда:

ELBA_API_KEY="ваш-api-ключ" node /absolute/path/to/elba-kontur-mcp/dist/index.js

stdout занят протоколом MCP. Диагностические сообщения сервер выводит только в stderr.

Инструменты MCP

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

Примеры запросов ассистенту:

• «Покажи мои организации в Эльбе».

• «Найди операции для работы с контрагентами».

• «Покажи схему создания счёта, но пока ничего не создавай».

• «Создай контрагента в организации … с такими реквизитами: …».

Настройки окружения

ELBA_API_BASE_URL полезен для тестового прокси. Не меняйте его на недоверенный адрес: сервер отправляет туда API-ключ.

Разработка

npm run check
npm test

При обновлении API замените openapi.json, затем выполните проверку и тесты. Клиент автоматически использует список маршрутов из схемы.

Версионирование и публикация

Проект использует Semantic Versioning:

• patch — исправления без изменения совместимости;

• minor — новые обратно совместимые возможности;

• major — несовместимые изменения MCP-инструментов или конфигурации.

Перед выпуском обновите CHANGELOG.md, убедитесь, что ветка main чистая, затем выберите тип версии:

npm run release:patch
# или npm run release:minor
# или npm run release:major

Команда обновит версии в package.json и package-lock.json, создаст коммит и Git-тег. Отправьте их вместе:

git push origin main --follow-tags

Тег vX.Y.Z запускает workflow .github/workflows/publish.yml: он сверяет тег с версией пакета, выполняет тесты и публикует пакет с provenance.

Для публикации добавьте в настройках GitHub-репозитория секрет Actions NPM_TOKEN с npm automation/granular access token. Ограничьте токен только этим пакетом и правом публикации.

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

• ключ не записывается в логи и ответы MCP;

• произвольные URL и неизвестные маршруты отклоняются;

• сетевой запрос ограничен таймаутом;

• ошибки API возвращаются без заголовков запроса;

• .env исключён из Git.

Любой MCP-инструмент с операциями POST, PUT или DELETE может менять данные в Эльбе. Проверяйте организацию, идентификаторы и тело запроса перед подтверждением действия.

Лицензия

MIT