@rcs-kz/bitrix24-mcp
Advanced tools
Production-grade MCP server for Bitrix24 Cloud — tools for CRM, Tasks, Users, and more.
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.
Три сценария использования:
docs/TOOLS.md.Самый простой путь. Ни один байт не уходит с вашей машины на наши серверы — 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 и вернёт таблицу. Готово.
Для отдела продаж или внедренца — одна установка в портале работает для всех пользователей; права определяются ролями 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.
Cowork — это режим Claude для не-разработчиков, где плагины устанавливаются в 2 клика.
.mcpbclaude 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>/"
}
}
}
}
Полный каталог tools с JSON-схемами: docs/TOOLS.md.
Готовые промпты с ожидаемыми chain-of-tools: docs/PROMPTS.md.
CRM — 26 tools
b24_crm_item_*destructive: true — Claude перед удалением обязательно спросит подтверждениеЗадачи — 8 tools
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)«В почте письмо от ceo@kalmpro.kz — клиент заинтересован купить мебельный набор на 2,4 млн тенге, срок — середина мая. Заведи лид, создай сделку в воронке „Входящие“, поставь задачу Саттарову перезвонить завтра к 15:00».
Chain: b24_crm_lead_add → b24_crm_deal_add → b24_tasks_add.
«Покажи все мои задачи на сегодня и запланированные встречи, сгруппируй по важности».
Chain: b24_user_current → b24_tasks_list (фильтр по responsibleId + deadline) → b24_calendar_event_list.
«У меня 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 говорит напрямую с вашим порталом.
Шифрование:
Audit:
events в SQLite + структурный JSON logОграничения:
Соответствие нормативке:
Reporting уязвимостей:
security@rcs.kz · 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.
Стек:
@modelcontextprotocol/sdk)Серверная часть (marketplace): PHP 8.1+ (чтобы не требовать Composer у клиентов RCS.KZ), SQLite, Nginx с TLS 1.3.
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 в режиме отладки
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.
.mcpbnpm 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).
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 };
},
};
src/tools/index.ts:export const ALL_TOOLS = [
// ... существующие
myTool,
];
Добавьте тест в tests/tools/<category>/<my_tool>.test.ts.
Сборка — npm run pack:mcpb автоматически подхватит новый tool в manifest и TOOLS.md.
@typescript-eslint/strict + Prettierhusky + lint-staged (typecheck + eslint только изменённых файлов)npm lockfile, не yarn/pnpm.mcpb, validateВ: Чем это лучше 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 извне не принимаются. Но мы рады:
[FR].well-known/security.txt); не публиковать в Issues до фиксаМы рассматриваем open-sourcing клиентского ядра (BitrixClient, rate-limiter, zod-schemas) под MIT/Apache-2.0 после v1.0 — следите за CHANGELOG.md.
Commercial EULA — см. LICENSE (короткая форма) и docs/legal/EULA.ru.md (расширенная, binding).
Кратко:
Санкционная совместимость: продукт недоступен в юрисдикциях под эмбарго (Иран, Сирия, КНДР, Куба, Крым, ДНР, ЛНР) и лицам в списках OFAC SDN / EU / РК. См. EULA §12.
Сделано в Казахстане для пользователей Claude и Bitrix24.
English version →
FAQs
Production-grade MCP server for Bitrix24 Cloud — tools for CRM, Tasks, Users, and more.
The npm package @rcs-kz/bitrix24-mcp receives a total of 39 weekly downloads. As such, @rcs-kz/bitrix24-mcp popularity was classified as not popular.
We found that @rcs-kz/bitrix24-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.