# Bitrix24 Tasks, CRM & Lists MCP Server

Типизированный MCP-сервер для Bitrix24 на Node.js/TypeScript. Даёт Claude
(или любому другому MCP-клиенту) 46 инструментов для работы с задачами и
проектами (воркгруппами/канбаном), CRM (сделки, контакты, пользователи,
активности) и Списками (Универсальные списки) через стандартный входящий
webhook Bitrix24 REST API — без сторонних кастомных модулей.

Bitrix24 — единственный источник истины: сервер ничего не кеширует и не
хранит производных копий бизнес-данных.

## Архитектура

```text
Claude/Cursor -> Docker MCP stdio -> Bitrix24 REST v2/v3
```

Опционально — второй, HTTP-транспорт с мультиаккаунтным OAuth-логином (для
claude.ai Team/браузер-коннекторов), backed небольшой Postgres-таблицей
аккаунтов:

```text
claude.ai -> HTTP + OAuth -> Bitrix24 REST v2/v3
                    |
                    +-> PostgreSQL (только таблица аккаунтов)
```

Подробности: [архитектура](docs/architecture.md), [модули](docs/modules.md),
[права доступа](docs/access-control.md),
[развёртывание](docs/deployment.md), [операции](docs/operations.md),
[удалённый доступ](docs/remote-access.md), [ручное тестирование](docs/manual-testing.md),
[примеры промптов](docs/user-prompts.md).

## Модули

Сервер устроен как ядро + подключаемые модули по доменам (`tasks`, `crm`,
`lists`) — каждый модуль можно отключить (`MCP_ENABLED_MODULES`), а свой
(в том числе полностью сторонний, вне этого репозитория) — подключить через
`MCP_EXTRA_MODULES`. Полный контракт модуля и как написать свой —
[docs/modules.md](docs/modules.md).

## Требования

- Docker Engine / Docker Desktop с Docker Compose v2;
- существующий портал Bitrix24;
- входящий webhook с нужными scope (`task`, `crm`, при необходимости
  `calendar`, `im`, `timeman`, `user`, `lists`);
- PostgreSQL нужен только для мультиаккаунтного HTTP-транспорта — обычный
  stdio-запуск с одним общим вебхуком работает вообще без базы.

Node.js/npm на хост устанавливать не нужно — все команды выполняются в
Docker. Для локальной разработки без Docker достаточно Node.js ≥20.

## Быстрый запуск

1. Скопируйте `.env.example` в `.env`, заполните `BITRIX_WEBHOOK_BASE`.
2. Проверьте, что `.env` не попадает в Git (`.gitignore` уже это делает).
3. Запустите MCP через stdio:

```powershell
docker compose build
docker compose run --rm -T mcp
```

Для Cursor/Claude Desktop проектный `.mcp.json` запускает ту же команду.
stdout зарезервирован для MCP-протокола; структурированные логи идут в
stderr.

Без Docker (локальная разработка):

```powershell
npm install
npm run dev
```

## Переменные окружения

### Bitrix24

- `BITRIX_WEBHOOK_BASE` — секретный URL вида `https://portal.example.ru/rest/123/token`. Не коммитьте и не выводите в лог.
- `BITRIX_DEFAULT_DEAL_CATEGORY` — имя CRM-воронки по умолчанию.
- `BITRIX_DEFAULT_GROUP_ID` — ID проекта/группы, используемый task-инструментами, когда пользователь не указал проект явно. Пустое/неположительное/нечисловое значение игнорируется.
- `BITRIX_REPO_GROUP_MAP` — JSON-объект `{"owner/repository":172}`, сопоставляющий имя репозитория с ID Bitrix24-проекта; ключи нормализуются в lower-case, некорректный JSON даёт пустую карту.

### Модули (см. docs/modules.md)

- `MCP_ENABLED_MODULES` — список id встроенных модулей через запятую (`tasks`, `crm`, `lists`). Не задано — включены все; пустая строка отключает все встроенные (останется только `bitrix_test_connection`).
- `MCP_EXTRA_MODULES` — сторонние модули вне репозитория: npm-пакеты и/или пути к файлам через запятую. Регистрируются всегда, если успешно загрузились, независимо от `MCP_ENABLED_MODULES`. Выполняет произвольный код с правами процесса — указывайте только то, чему доверяете.

### PostgreSQL (только для мультиаккаунтного HTTP-транспорта)

- `DATABASE_URL`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`.

### Удалённый HTTP-транспорт (опционально)

- `MCP_TRANSPORT` — `stdio` (по умолчанию) или `http`. Влияет только на сервис `mcp-http` в docker-compose.
- `MCP_HTTP_PORT` — порт HTTP-сервера, по умолчанию `3000`.
- `MCP_PUBLIC_URL` — внешний HTTPS-адрес сервера (адрес туннеля при тесте, домен при постоянном хостинге); используется как OAuth issuer.
- Каждый аккаунт (логин + пароль + свой личный Bitrix-вебхук + роль) создаётся и управляется командой `npm run manage-accounts` (см. [docs/access-control.md](docs/access-control.md)). `MCP_AUTH_USERNAME`/`MCP_AUTH_PASSWORD_HASH` — только одноразовый bootstrap: если `mcp_accounts` пуста при старте, из них и `BITRIX_WEBHOOK_BASE` заводится один аккаунт с ролью `admin`.
- `MCP_TOKEN_TTL_SECONDS`, `MCP_REFRESH_TOKEN_TTL_SECONDS` — время жизни access/refresh токенов.

Подробный пошаговый запуск (включая тест через ngrok/Cloudflare Tunnel и подключение из claude.ai): [docs/remote-access.md](docs/remote-access.md).

## MCP-инструменты — 46

По умолчанию, при всех включённых встроенных модулях — см. [Модули](#модули)
выше. Если отключить часть через `MCP_ENABLED_MODULES`, инструментов будет
меньше.

Полный список с примерами вызова — [docs/manual-testing.md](docs/manual-testing.md).

### Задачи и проекты — 26

connection · list/get/history/messages/checklist/result · update ·
create/start/complete · move stage · project stages (list/create) · projects
(list/create/members: list/add/remove/update-role) · calendar
(find-slot/schedule-meeting) · timesheet · worktime report ·
send-direct-message.

### CRM — 18

сделки (categories/stages/list/get/create/update/move/comment) · контакты
(list/get/find/create/update) · пользователи (list/get) · активности
(list/create).

### Списки (Lists) — 2

`bitrix_lists_search_letters`, `bitrix_lists_get_letter_file` — поиск и
скачивание вложений в реестре входящей/исходящей корреспонденции
(Универсальные списки). Требует настройки под ваш портал — см.
[docs/manual-testing.md](docs/manual-testing.md#списки-lists).

Все write-инструменты требуют `confirm=true`. Универсального REST-инструмента нет — каждый tool валидирует и ограничивает набор полей отдельно.

## Тесты и качество

```powershell
docker compose --profile test run --rm test
docker compose --profile test down --volumes
```

Локально:

```powershell
npm run check   # typecheck + lint + format:check + test + build
```

Bitrix integration smoke ([tests/integration](tests/integration)) запускается только при `RUN_BITRIX_INTEGRATION_TESTS=true`, запись — только при дополнительном подтверждении. По умолчанию реальные записи никогда не выполняются.

## Backup и восстановление (мультиаккаунтный HTTP-транспорт)

```powershell
docker compose exec -T postgres pg_dump -U bitrix_mcp -d bitrix_mcp -Fc > bitrix-mcp.backup
```

Актуально только если используется `mcp-http` — таблица `mcp_accounts`
хранит логины/роли/личные вебхуки аккаунтов. Для обычного stdio-запуска с
одним вебхуком базы нет и бэкапить нечего.

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

- удалённый HTTP-транспорт (`mcp-http`) хранит OAuth-клиентов и токены в
  памяти процесса (не переживает рестарт контейнера); аккаунты
  (логин/пароль/роль/вебхук) хранятся в Postgres и рестарт переживают — см.
  [docs/remote-access.md](docs/remote-access.md).
- роль аккаунта (`developer`/`business_analyst`/`product_owner`/`admin`) —
  описательное поле, ничем не гейтится "из коробки" — см.
  [docs/access-control.md](docs/access-control.md).
- нет универсального REST passthrough-инструмента — каждый tool сознательно
  ограничивает набор полей, которые можно менять.