bitrix24-mcp

Production-grade MCP-сервер для Bitrix24 — подключите Claude (Cowork, Claude Desktop, Claude Code) к CRM, задачам, контактам и календарю вашего портала. 45 tools, билингвальный, local-first, совместим с Законом РК 94-V и GDPR.

Зачем это

Вы пишете Claude: «Создай сделку на 2,4 млн для ТОО „КалмПро Трейдинг“, повесь задачу менеджеру Саттарову на завтра, приложи коммерческое предложение из почты» — и Claude делает это в вашем Bitrix24 портале за 4 секунды. Без кода, без копирования ID, без Zapier, без утечки данных на сторонние SaaS.

Три сценария использования:

1. Индивидуальный менеджер — Cowork или Claude Desktop на MacBook. Webhook, 5 минут, данные никогда не покидают ваш ноутбук и ваш Bitrix24.
2. Отдел продаж / внедренец — OAuth-установка из Bitrix24 marketplace. Клик «Установить», claim-код, работают все менеджеры отдела, каждому — свой портал, свои права.
3. Enterprise / on-premise — self-hosted MCP-сервер на контуре клиента. Белые лейблы, pre-audited код, SLA.

Что внутри

• 45 tools в 9 категориях — CRM (26), Задачи (8), Коммуникации (3), Директория (3), Утилиты (5). Полный список: docs/TOOLS.md.
• Multi-tenant OAuth — один сервер обслуживает N порталов Bitrix24, refresh-токены зашифрованы AES-256-GCM, claim-коды 192 бита энтропии с TTL 15 мин и single-use.
• Webhook-mode — zero-server режим: MCP-сервер работает на машине пользователя, разговаривает напрямую с API портала, наши серверы не в пути данных.
• Rate-limiter и retries — Bitrix24 API лимитит запросы (2 rps), наш клиент автоматически обходит лимиты через batch-запросы (до 50 операций в одном HTTP-хопе).
• Билингва — все ошибки, страницы установки, EULA и Privacy Policy на русском (binding) и английском (convenience). Первичный рынок — Казахстан/Россия.
• Privacy-first — сервер RCS.KZ хранит OAuth-токены ≤ 15 минут в фазе claim, после consume — очищается. Соответствие Закону РК 94-V и GDPR.
• 212 unit + 39 integration тестов — 100% покрытие tool-слоя. Integration gated — запускаются только с реальным webhook-url.

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

Вариант A — Claude Desktop + Webhook (5 минут, local-first)

Самый простой путь. Ни один байт не уходит с вашей машины на наши серверы — MCP говорит напрямую с вашим Bitrix24.

Шаг 1. Получите webhook-URL в вашем портале:

Bitrix24 → Приложения → Разработчикам → Другое → Входящий вебхук

Отметьте права минимально: CRM, Задачи, IM, Календарь, Пользователи. Сохраните URL вида:

https://your-portal.bitrix24.ru/rest/1/a1b2c3d4e5f6abcdef/

Шаг 2. Скачайте .mcpb:

curl -L https://rcs.kz/bitrix24-mcp/download/latest.mcpb -o bitrix24-mcp.mcpb

Шаг 3. В Claude Desktop: Settings → Extensions → Install from file… → выберите .mcpb. В диалоге конфигурации вставьте webhook-URL.

Шаг 4. В новом чате:

«Покажи активные сделки с суммой больше 1 млн ₸»

Claude вызовет b24_crm_deal_list и вернёт таблицу. Готово.

Вариант B — Marketplace OAuth (для команды)

Для отдела продаж или внедренца — одна установка в портале работает для всех пользователей; права определяются ролями Bitrix24.

Шаг 1. В вашем Bitrix24 портале: Приложения → Marketplace → Поиск «bitrix24-mcp» → Установить. Или прямая ссылка: https://rcs.kz/bitrix24-mcp/install.

Шаг 2. После установки откроется страница с claim-кодом (48 hex-символов). Скопируйте его — он активен 15 минут.

Шаг 3. На машинах пользователей установите .mcpb из варианта A. Вместо webhook-URL в конфигурации выберите «OAuth» и вставьте claim-код — расширение обменяет его на токен и запомнит в системном keychain.

Шаг 4. Каждый менеджер использует свою сессию — права CRM берутся из его роли в портале. Claude не может видеть сделки, которые менеджер не видит в веб-интерфейсе.

Приватность: после обмена claim-кода токены на нашем сервере очищаются, MCP говорит напрямую с вашим порталом. Подробнее: PRIVACY.ru.md §5.

Вариант C — Cowork (для пользователей Claude)

Cowork — это режим Claude для не-разработчиков, где плагины устанавливаются в 2 клика.

1. Откройте Cowork → Customize → Plugins → Upload .mcpb
2. В настройках плагина выберите webhook или OAuth (как в вариантах A/B)
3. Начните диалог

Вариант D — Claude Code (для разработчиков)

claude mcp add bitrix24 --mcpb bitrix24-mcp.mcpb

Или вручную в ~/.claude/mcp.json:

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/path/to/bitrix24-mcp/dist/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-portal.bitrix24.ru/rest/1/<token>/"
      }
    }
  }
}

Что Claude умеет с вашим Bitrix24

Полный каталог tools с JSON-схемами: docs/TOOLS.md. Готовые промпты с ожидаемыми chain-of-tools: docs/PROMPTS.md.

CRM — 26 tools

• Сделки (deal): список / получить / создать / обновить / удалить + управление стадиями (категории/статусы) + timeline-комментарии
• Контакты, компании, лиды — полный CRUD + связки с сделками
• Smart Processes — унифицированные операции над кастомными сущностями через b24_crm_item_*
• Удаление идёт через отдельные tools с destructive: true — Claude перед удалением обязательно спросит подтверждение

Задачи — 8 tools

• list / get / add / update / complete / delegate
• Комментарии и вложенные чек-листы
• Привязка задач к сущностям CRM (через ufCrmTask)

Коммуникации — 3 tools

• b24_im_notify — отправить внутреннее уведомление пользователю
• b24_calendar_event_add / b24_calendar_event_list — встречи с участниками и напоминаниями

Директория — 3 tools

• b24_user_current — контекст текущего пользователя (полезно для «кому назначить»)
• b24_user_search — поиск сотрудников по ФИО/email/отделу
• b24_department_list — дерево оргструктуры

Утилиты — 5 tools

• b24_util_app_info — информация о приложении, проверка соединения
• b24_util_fields — метаданные полей сущности (обязательно перед нестандартными фильтрами)
• b24_util_batch_execute — до 50 REST-операций в одном HTTP-хопе
• b24_util_rest_raw — escape-hatch для нестандартных методов (закрыт confirm-gate)

Примеры промптов

1. Создать сделку из письма (3 tools)

«В почте письмо от [email protected] — клиент заинтересован купить мебельный набор на 2,4 млн тенге, срок — середина мая. Заведи лид, создай сделку в воронке „Входящие“, поставь задачу Саттарову перезвонить завтра к 15:00».

Chain: b24_crm_lead_add → b24_crm_deal_add → b24_tasks_add.

2. План дня для менеджера (2 tools)

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

Chain: b24_user_current → b24_tasks_list (фильтр по responsibleId + deadline) → b24_calendar_event_list.

3. Batch-перевод стадий (1 batch-tool)

«У меня 47 сделок в стадии „Подготовка КП“ старше 14 дней. Переведи их все в „Потерян — нет ответа“ и оставь комментарий в timeline».

Chain: b24_crm_deal_list → один b24_util_batch_execute с 47 × crm.deal.update + 47 × crm.timeline.comment.add.

Полный каталог — docs/PROMPTS.md (12 развёрнутых сценариев).

Безопасность и приватность

Local-first: в webhook-режиме данные никогда не покидают вашу машину. В OAuth-режиме сервер RCS.KZ участвует только в первые 5 секунд обмена claim-кода, после чего MCP говорит напрямую с вашим порталом.

Шифрование:

• Webhook-токены: macOS Keychain / Windows Credential Manager / libsecret (Linux)
• OAuth refresh-токены на сервере: AES-256-GCM (sodium с fallback на openssl), ключ 32 байта из env
• Claim-коды: 192 бита энтропии (24 случайных байта), TTL 15 минут, single-use

Audit:

• Все события на сервере (установка, обмен claim, удаление) логируются в таблицу events в SQLite + структурный JSON log
• В логах токены маскируются (первые 4 + последние 4 символа)
• Retention: серверные логи — 30 дней, токены — до uninstall

Ограничения:

• Сервер удерживает токены ≤ 15 минут в claim-фазе — это соответствует PRIVACY §5
• Refresh-токены шифруются при хранении и НЕ передаются локальному MCP-клиенту в v1
• TLS 1.3 only на rcs.kz

Соответствие нормативке:

• Закон РК 94-V «О персональных данных» — ответственный орган: Комитет по инфобезопасности МЦРИАП РК
• GDPR-rights (доступ / удаление / портабельность) — описаны в PRIVACY §7
• Санкционная совместимость — OFAC SDN, ЕС, РК; запрещённые юрисдикции в EULA §12

Reporting уязвимостей:
[email protected] · PGP-ключ на rcs.kz/.well-known/security.txt · SLA ответа — 72 часа

Тарифы

| Tier | Цена | Tools | Порталов | Call-home | Поддержка | |---|---|---|---|---|---| | Free | 0 ₸ | 12 read-only (списки, fields, user_current) | 1 | нет | community | | Pro | 3 490 ₸ / мес | все 45 | 1 | 1×/24ч license check | email 48ч | | Business | 9 990 ₸ / мес | + white-label, + custom UF-поля, + приоритетная batch-очередь | 5 | 1×/24ч | email 24ч, chat | | Enterprise | от 49 990 ₸ / мес | + on-prem deploy, + custom tools, + pre-audited build | ∞ | по договору | SLA 4ч, dedicated CSM |

Что значит «call-home»: раз в 24 часа клиент делает HTTPS-запрос с license_key + member_id + version на lic.rcs.kz — не более. Никакие данные CRM не передаются. Grace period — 7 дней офлайн без блокировки. См. PRIVACY §3.3.

Возврат: в течение 14 дней с даты оплаты для годовых подписок. Детали — EULA §6.

Оплата: Kaspi Gold (QR), карта (Visa/Master/UnionPay), безнал для ТОО/ИП. Для Enterprise — договор оферты и закрывающие документы в течение 5 рабочих дней.

Архитектура

Три пути данных в зависимости от режима:

┌─ Webhook mode (Free / Self-hosted) ────────────────────────┐
│                                                            │
│   Claude ──► MCP server ──► Bitrix24 portal REST          │
│    (chat)    (user's Mac)    (customer's tenant)          │
│                                                            │
│   rcs.kz НЕ в пути данных                                 │
└────────────────────────────────────────────────────────────┘

┌─ OAuth marketplace install (Pro / Business) ───────────────┐
│                                                            │
│   Bitrix24 ──install──► rcs.kz/install.php ──claim──┐     │
│                              │                       │     │
│                              ▼                       ▼     │
│                        TokenStore SQLite        user sees  │
│                        (< 15 min)               claim_code │
│                              │                       │     │
│                              ▼                       │     │
│   User pastes claim in MCP ──► oauth/callback.php ◄─┘     │
│                                    │                       │
│                                    ▼                       │
│             MCP gets access_token  │ rcs.kz drops row     │
│                                    ▼                       │
│   Claude ──► MCP ──► Bitrix24 (data path, rcs.kz out)     │
└────────────────────────────────────────────────────────────┘

┌─ License verification (Pro+) ──────────────────────────────┐
│                                                            │
│   MCP ──1x/24h──► lic.rcs.kz  (sends: key + member_id +   │
│                                        version; < 400 B)   │
│                   ▲                                        │
│                   └── signed JWT reply: valid-until + tier │
└────────────────────────────────────────────────────────────┘

Полная архитектура (arc42): docs/arc42/.
ADR-решения: docs/ADR/.
Runtime-диаграммы (sequence, component, state): docs/arc42/6-runtime.md.

Стек:

• Node.js 20.18+, TypeScript 5.4, ESM
• MCP SDK (@modelcontextprotocol/sdk)
• Zod — схемы tools
• Axios — Bitrix REST клиент
• Keytar — системный keychain
• SQLite3 (только на сервере marketplace, не в MCP)
• Vitest — unit + integration

Серверная часть (marketplace): PHP 8.1+ (чтобы не требовать Composer у клиентов RCS.KZ), SQLite, Nginx с TLS 1.3.

Для разработчиков

Dev setup

git clone https://github.com/rcs-kz/bitrix24-mcp.git
cd bitrix24-mcp
nvm use            # Node 20.18
npm ci
cp .env.example .env
# заполнить BITRIX24_WEBHOOK_URL в .env
npm run typecheck  # tsc --noEmit
npm run test       # vitest run
npm run dev        # stdio MCP server в режиме отладки

Отладка через MCP Inspector

npx @modelcontextprotocol/inspector node --import tsx/esm src/index.ts

Inspector откроется в браузере, покажет все 45 tools и позволит вызывать их с любыми аргументами.

Тесты

npm run test                # 212 unit тестов
npm run test:integration    # 39 integration тестов (требует BITRIX24_WEBHOOK_URL)
npm run test:e2e            # live-API smoke (6 сценариев)

Integration-тесты запускаются только с реальным webhook. Без env-переменной они skip-аются. Не коммитьте webhook-URL в git — используйте .env, который в .gitignore.

Сборка .mcpb

npm run build:docs       # docs/TOOLS.md + manifest.json
npm run pack:mcpb        # dist/bitrix24-mcp.mcpb
npx @anthropic-ai/mcpb validate manifest.json

Итоговый .mcpb — 29 МБ (с .mcpbignore, без TypeScript/vitest в bundle).

Добавить свой tool

1. Создайте файл src/tools/<category>/<my_tool>.ts:

import { z } from 'zod';
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { getClient } from '../../bitrix/client.js';

export const myToolSchema = z.object({
  dealId: z.number().int().positive(),
});

export const myTool: Tool<typeof myToolSchema> = {
  name: 'b24_crm_my_tool',
  description: 'Мой кастомный tool над сделкой',
  inputSchema: myToolSchema,
  annotations: { readOnlyHint: true },
  async handler({ dealId }, ctx) {
    const client = await getClient(ctx);
    const { result } = await client.call('crm.deal.get', { ID: dealId });
    return { deal: result };
  },
};

2. Зарегистрируйте в src/tools/index.ts:

export const ALL_TOOLS = [
  // ... существующие
  myTool,
];

3. Добавьте тест в tests/tools/<category>/<my_tool>.test.ts.

4. Сборка — npm run pack:mcpb автоматически подхватит новый tool в manifest и TOOLS.md.

Code style

• @typescript-eslint/strict + Prettier
• Pre-commit — husky + lint-staged (typecheck + eslint только изменённых файлов)
• Зависимости — npm lockfile, не yarn/pnpm
• CI — GitHub Actions на push и PR: typecheck, test, build .mcpb, validate

FAQ

В: Чем это лучше Zapier / Make / n8n?
О: bitrix24-mcp — это не интеграционная платформа, а MCP-сервер: инструмент, который Claude вызывает в реальном времени прямо из диалога. Zapier — это готовые цепочки (триггер → действие). Здесь Claude сам выбирает и комбинирует tools под ваш конкретный запрос. Плюс ни один байт вашей CRM не проходит через сторонний SaaS.

В: Нужен ли у меня аккаунт OpenAI / Anthropic?
О: Нужен аккаунт Claude (Anthropic) — платный или Pro/Team/Enterprise. bitrix24-mcp — это расширение для Claude, не самостоятельный бот. MCP-сервер сам не делает LLM-вызовов.

В: Будет ли это работать с on-premise Bitrix24?
О: Да, webhook-mode совместим с любой self-hosted инсталляцией Bitrix24 (включая «Коробку»). OAuth marketplace — только для Cloud. Enterprise-тариф включает on-prem deploy самого MCP-сервера.

В: Что будет, если Bitrix24 изменит REST API?
О: Наш клиент построен поверх публичного стабильного API (crm.*, tasks.*, user.*). Мы поддерживаем breaking changes в течение 90 дней от анонса Bitrix; patch-версии выпускаются автоматически. История совместимости — CHANGELOG.md.

В: А если у пользователя мало прав в CRM — Claude сможет их обойти?
О: Нет. Все вызовы идут от имени авторизованного пользователя (либо владельца webhook, либо OAuth-юзера). Bitrix24 применяет его ACL. Claude физически не может увидеть сделку, которую пользователь не видит в веб-интерфейсе портала.

В: Как обновляться?
О: В Cowork — автоматически. В Claude Desktop — стандартный диалог «Обновить расширение» при выходе новой версии. Breaking changes всегда major-версия (semver).

В: Что входит в open-core часть?
О: Клиент Bitrix REST (rate-limiter, retries), zod-схемы, утилиты логирования — MIT / Apache-2.0, отдельный репозиторий. Обфусцированные bundle-артефакты (licensing, tier-gating) — под EULA.

В: Можно ли пересылать данные клиентов третьим сторонам?
О: Нет — это основа нашего контракта. Serverside-часть (marketplace) обменивает токены и отдаёт их локальному MCP, больше ничего. Никакой телеметрии, никакой аналитики на рекламные SDK. См. PRIVACY §2.

В: Локализация?
О: Интерфейс установки — RU + EN. Tool descriptions в manifest — RU-first (чтобы Claude формулировал промпты на русском естественнее). Документация и EULA — RU (binding) + EN (convenience). Поддержку других языков обсуждаем при спросе.

Документация

| Документ | Описание | |---|---| | docs/TOOLS.md | Полный каталог 45 tools с JSON-схемами и аннотациями | | docs/PROMPTS.md | 12 готовых промптов с разбором chain-of-tools | | docs/arc42/ | Архитектурная документация arc42 (12 разделов) | | docs/ADR/ | Architecture Decision Records (принятые решения) | | docs/legal/PRIVACY.ru.md | Политика конфиденциальности (РК 94-V + GDPR) | | docs/legal/EULA.ru.md | Лицензионный договор | | marketplace/README.md | Деплой серверной части (для интеграторов) | | ROADMAP.md | План-факт по фазам, оценки часов | | CLAUDE.md | Инструкции для Claude-сессий разработки |

Участие

Проект proprietary — pull-requests извне не принимаются. Но мы рады:

• Bug reports — GitHub Issues (публичный трекер): https://github.com/rcs-kz/bitrix24-mcp/issues
• Feature requests — через [email protected] с тегом [FR]
• Security disclosures — [email protected] (PGP-ключ в .well-known/security.txt); не публиковать в Issues до фикса
• Интеграторы и франчайзи — [email protected], обсудим white-label и реферальную программу

Мы рассматриваем open-sourcing клиентского ядра (BitrixClient, rate-limiter, zod-schemas) под MIT/Apache-2.0 после v1.0 — следите за CHANGELOG.md.

Лицензия

Commercial EULA — см. LICENSE (короткая форма) и docs/legal/EULA.ru.md (расширенная, binding).

Кратко:

• Free tier — бесплатно, без гарантий, до 1 портала, 12 read-only tools
• Pro / Business / Enterprise — платная подписка, см. тарифы
• Open-core части (клиент, схемы) — отдельный репозиторий после v1.0 под MIT/Apache-2.0
• Реверс-инжиниринг обфусцированных bundles, обход лицензии, перепродажа без письменного разрешения — запрещены (ст. 985 ГК РК)

Санкционная совместимость: продукт недоступен в юрисдикциях под эмбарго (Иран, Сирия, КНДР, Куба, Крым, ДНР, ЛНР) и лицам в списках OFAC SDN / EU / РК. См. EULA §12.

Контакты

• Владелец: ИП Саттаров Ш.С., RCS.KZ — https://rcs.kz
• Поддержка: [email protected]
• Продажи и партнёрство: [email protected]
• Security: [email protected]
• Юридические запросы: [email protected]
• Адрес: Республика Казахстан, г. Алматы (конкретный офис — на запрос)