# Руководство по Развёртыванию Bitrix24 MCP Server
## Содержание
- [Быстрый старт](#быстрый-старт)
- [Получение Webhook URL](#получение-webhook-url)
- [Варианты развёртывания](#варианты-развёртывания)
- [Подключение к MCP клиентам](#подключение-к-mcp-клиентам)
- [Безопасность](#безопасность)
- [Мониторинг](#мониторинг)
---
## Быстрый старт
### 1. Клонирование репозитория
```bash
git clone https://github.com/kartochka/bitrix24-mcp.git
cd bitrix24-mcp
```
### 2. Настройка окружения
```bash
# Скопировать пример конфигурации
cp .env.example .env
# Отредактировать .env и указать ваш Bitrix24 Webhook URL
nano .env
```
### 3. Запуск (выберите один из вариантов)
**Локальный запуск (STDIO):**
```bash
export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/your_secret/"
uv run bitrix24-mcp
```
**Удалённый запуск (HTTP):**
```bash
export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/your_secret/"
export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
uv run bitrix24-mcp
```
**Запуск через Docker:**
```bash
docker-compose up -d
```
---
## Получение Webhook URL
### Шаг 1: Войдите в Bitrix24
Перейдите в ваш портал Bitrix24 (например, `https://your-company.bitrix24.ru`)
### Шаг 2: Откройте раздел разработчика
1. Нажмите на **Приложения** в левом меню
2. Выберите **Разработчикам** или **Developer resources**
3. Нажмите **Другое** → **Входящий вебхук** (Incoming webhook)
### Шаг 3: Настройте права доступа
Минимально необходимые права:
- ✅ **CRM** - для доступа к контактам и сделкам
- ✅ **Пользователи (users)** - опционально, для информации о пользователях
### Шаг 4: Получите URL
После сохранения вы получите URL в формате:
```
https://your-domain.bitrix24.ru/rest/1/abc123xyz789/
```
> ⚠️ **ВАЖНО:** Храните этот URL в секрете! Он даёт полный доступ к вашим CRM данным.
---
## Варианты развёртывания
### Вариант 1: Локальный запуск (для разработки)
```bash
# Установка зависимостей
uv sync
# Запуск
BITRIX_WEBHOOK_URL="..." uv run bitrix24-mcp
```
Используйте для интеграции с Claude Desktop и другими локальными клиентами.
### Вариант 2: Docker (рекомендуется для продакшена)
```bash
# Сборка образа
docker build -t bitrix24-mcp .
# Запуск контейнера
docker run -d \
--name bitrix24-mcp \
-p 8000:8000 \
-e BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/secret/" \
-e MCP_TRANSPORT=streamable-http \
bitrix24-mcp
```
### Вариант 3: Docker Compose
```bash
# Создать .env файл с BITRIX_WEBHOOK_URL
echo 'BITRIX_WEBHOOK_URL=https://your-domain.bitrix24.ru/rest/1/secret/' > .env
# Запуск
docker-compose up -d
# Просмотр логов
docker-compose logs -f
```
### Вариант 4: Облачные платформы
#### Railway
```bash
# Установить Railway CLI
npm install -g @railway/cli
# Деплой
railway login
railway init
railway up
```
#### Render
1. Подключите GitHub репозиторий
2. Выберите тип: Web Service
3. Укажите переменные окружения
4. Deploy
#### Google Cloud Run
```bash
# Сборка и push образа
gcloud builds submit --tag gcr.io/PROJECT_ID/bitrix24-mcp
# Деплой
gcloud run deploy bitrix24-mcp \
--image gcr.io/PROJECT_ID/bitrix24-mcp \
--platform managed \
--set-env-vars BITRIX_WEBHOOK_URL="...",MCP_TRANSPORT=streamable-http
```
---
## Подключение к MCP клиентам
### Claude Desktop (локальный режим)
Добавьте в `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"bitrix24": {
"command": "uv",
"args": ["run", "--directory", "/path/to/bitrix24-mcp", "bitrix24-mcp"],
"env": {
"BITRIX_WEBHOOK_URL": "https://your-domain.bitrix24.ru/rest/1/secret/"
}
}
}
}
```
### HTTP клиенты (удалённый режим)
После запуска сервера с HTTP транспортом, подключитесь:
```
URL: http://your-server:8000/mcp
```
Пример конфигурации для MCP клиента:
```json
{
"mcpServers": {
"bitrix24": {
"url": "http://your-server:8000/mcp",
"transport": "streamable-http"
}
}
}
```
---
## Безопасность
### ✅ Рекомендации
1. **HTTPS обязателен для продакшена**
```bash
# Используйте reverse proxy (nginx, caddy)
# с SSL сертификатом от Let's Encrypt
```
2. **Ограничьте права Webhook**
- Давайте только необходимые разрешения в Bitrix24
3. **Используйте переменные окружения**
- Никогда не храните секреты в коде
- Используйте .env файл (не коммитьте в git!)
4. **Firewall**
- Ограничьте доступ к порту 8000 только доверенным IP
### ⚠️ Чего избегать
- ❌ Не публикуйте Webhook URL в публичных репозиториях
- ❌ Не запускайте без HTTPS в интернете
- ❌ Не давайте избыточные права webhook'у
---
## Мониторинг
### Логи
```bash
# Docker
docker logs -f bitrix24-mcp
# Docker Compose
docker-compose logs -f
# Локальный запуск
LOG_LEVEL=DEBUG uv run bitrix24-mcp
```
### Health Check
```bash
curl http://localhost:8000/health
```
### Метрики (планируется)
- Количество запросов к Bitrix24 API
- Время ответа
- Ошибки
---
## Поддержка
- **Issues:** https://github.com/kartochka/bitrix24-mcp/issues
- **Документация Bitrix24 API:** https://dev.1c-bitrix.ru/rest_help/
