b24-mcp

Локальный MCP-сервер к Битрикс24. Даёт AI-агенту свежие данные твоего портала — календарь, задачи и обсуждения в них, чаты, проекты-коллабы, AI-разборы звонков, карточки людей.

Только чтение. Работает с любым порталом — облачным или коробочным — через твой личный входящий вебхук.

Зачем это, если агент и так умеет HTTP

Агент может ходить в REST сам. Но тогда:

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

Сервер убирает это: агент вызывает бизнес-операцию (tasks_list, task_chat), а транспорт, версии, пагинация и нормализация живут внутри. Наружу выставлены только чтение и только перечисленные операции — raw-REST не выставлен вообще.

Что умеет (13 инструментов)

Инструмент	Что делает
whoami	Кто владелец вебхука — быстрая проверка, что связь живая
person_find	Найти человека: должность, отдел, контакты, активен ли
calendar_events	События за окно: время, участники, кто организатор, встреча это или личный блок
tasks_list	Задачи человека в роли responsible / originator / auditor
task_get	Шапка задачи: описание, статус, дедлайн, есть ли чат
task_chat	Обсуждение внутри задачи — там суть, а не в полях
tasks_updates	Что шевелится в своих задачах за окно + какие появились новые
chat_read	Прочитать диалог: групповой чат или личку
projects_list	Проекты-коллабы по свежести активности
project_chats	Из чего состоит проект: дочерние чаты
project_read	Обсуждение в чате проекта
followups_list	Звонки с готовым AI-разбором за окно
followup_get	Разбор звонка: тема, договорённости, action items, расшифровка

Ответы нормализованы: списки приходят как {items, count, limit}, разметка вычищена, лимиты зажаты.

Установка

Нужен Python 3.11+.

git clone <этот-репозиторий> b24-mcp && cd b24-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e .

Настройка

1. Выпусти входящий вебхук на своём портале. Раздел разработчика: Приложения → Разработчикам → Другое → Входящий вебхук.

Права (scope), которые использует сервер:

Scope	Для чего
user, department	люди и оргструктура
calendar	события
task, tasks_extended	задачи
im	чаты: задач, личные, групповые, проектов
call	AI-разборы звонков (без него работает всё остальное)

Меньше прав — меньше риск. Начни без call, добавишь, когда понадобятся звонки.

2. Положи вебхук в .env:

cp .env.example .env
chmod 600 .env          # сервер откажется читать файл, доступный другим

B24_WEBHOOK=https://<твой-портал>/rest/<число>/<токен>/
B24_USER_ID=<твой id>   # необязательно: определится сам через user.current

3. Подключи к своему MCP-клиенту. Пример для Claude Code (~/.claude.json):

{
  "mcpServers": {
    "b24": {
      "command": "/абсолютный/путь/b24-mcp/.venv/bin/python",
      "args": ["-m", "b24_mcp.server"],
      "env": { "B24_MCP_ENV": "/абсолютный/путь/b24-mcp/.env" }
    }
  }
}

Перезапусти клиент и спроси агента: «проверь связь с порталом» — он вызовет whoami.

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

• Токен живёт в .env с правами 600. Сервер проверяет права при старте и отказывается работать, если файл читается другими.
• Токен не попадает ни в ответы инструментов, ни в логи, ни в тексты ошибок. Логируется имя операции и время, не URL.
• Только чтение. Клиент создаётся с запретом write-методов на уровне транспорта, а наружу выставлены лишь перечисленные операции. Даже ошибка в коде инструмента не создаст задачу и не отправит сообщение.
• Честная граница: это снимает класс «секрет случайно утёк в вывод команды», но не отбирает у агента шелл. Если у него есть доступ к файловой системе, он по-прежнему может прочитать .env — как и любой процесс под твоим пользователем.
• Видно только то, где владелец вебхука участник. Чужие приватные чаты и события сервер не достанет.
• Утёк токен — отзови вебхук на портале и выпусти новый; менять придётся только .env.

Разработка

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q --asyncio-mode=auto

Тесты идут без сети. Они пинят список инструментов (новый не появится молча), барьер «только чтение», контракт нормализации и формы ответов портала — включая те, на которых легко промахнуться.

Две ловушки контракта, стоившие отладки ((зафиксированы тестами):

• Расшифровка звонка лежит в поле transcription (не transcript), саммари приходит сегментами ({segments: [{title, summary}]}), договорённости и задачи — под ключами agreement / actionItem, а не text. Промах даёт молча пустой ответ, а не ошибку.
• Участник звонка идентифицируется полем userId, не id. Чтение id вернёт None — и участника не связать с человеком.

Границы

Сервер намеренно не делает:

• write-операции — не создаёт задачи, не отправляет сообщения, не меняет портал;
• тяжёлые прогоны — сплошной прочёс всей переписки за месяц, выгрузку отчётов за квартал, резюмируемые обходы с чекпоинтами. Вызов инструмента живёт внутри одного обращения агента: там есть потолок времени и негде сохранить прогресс. Такие задачи решаются отдельным скриптом, а не MCP-инструментом.

Лицензия

MIT.