b24-mcp

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

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

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

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

• на каждый запрос он собирает URL, помнит имена методов и версии API, парсит ответ;

• токен проходит через его окружение на каждом вызове;

• ничто не мешает ему вызвать метод, меняющий портал.

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

Related MCP server: bitrix24-mcp-server

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

Ответы нормализованы: списки приходят как {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), которые использует сервер:

Меньше прав — меньше риск. Начни без 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.