bitrix24-mcp

English · Русский

MCP server that lets AI agents (Claude, ChatGPT, Cursor, your own agents) work with a Bitrix24 portal: CRM deals, contacts, leads and tasks.

Unofficial project, not affiliated with 1C-Bitrix.

Русский

Что умеет

По умолчанию сервер только читает. Инструменты записи появляются при BITRIX24_READ_ONLY=false.

Быстрый старт

1. Создайте входящий вебхук в Bitrix24. Разработчикам → Другое → Входящий вебхук. Дайте только нужные права (crm, task, user). Скопируйте URL вида https://ваш-портал.bitrix24.kz/rest/1/xxxxxxxx/. Это секрет: с ним можно действовать в CRM от имени пользователя вебхука.

2. Подключите к Claude Code:

claude mcp add bitrix24 \
  -e BITRIX24_WEBHOOK_URL="https://ваш-портал.bitrix24.kz/rest/1/xxxxxxxx/" \
  -- uvx --from git+https://github.com/Rip-07/bitrix24-mcp bitrix24-mcp

Или к Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "bitrix24": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Rip-07/bitrix24-mcp", "bitrix24-mcp"],
      "env": { "BITRIX24_WEBHOOK_URL": "https://ваш-портал.bitrix24.kz/rest/1/xxxxxxxx/" }
    }
  }
}

3. Спросите агента: «покажи сделки на стадии "Переговоры"» или «найди контакт по номеру +7 701 123 45 67».

Docker (HTTP-режим для удалённых агентов)

cp .env.example .env   # заполните BITRIX24_WEBHOOK_URL и MCP_AUTH_TOKEN
docker compose up -d --build
curl http://127.0.0.1:8000/health

MCP-эндпоинт: http://127.0.0.1:8000/mcp. Клиент должен передавать заголовок Authorization: Bearer <MCP_AUTH_TOKEN>. Без токена HTTP-режим не запустится. Наружу публикуйте только через обратный прокси с TLS.

Настройки

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

• Режим только чтения по умолчанию, запись включается явно.
• Токен вебхука маскируется в логах и сообщениях об ошибках.
• Имена методов проверяются, произвольные пути к API не принимаются.
• HTTP-режим требует Bearer-токен. Docker-образ работает от непривилегированного пользователя.
• Повторные запросы при лимите Bitrix24 (QUERY_LIMIT_EXCEEDED).

Частые проблемы

• CERTIFICATE_VERIFY_FAILED на macOS с Python из python.org: выполните /Applications/Python 3.x/Install Certificates.command или задайте SSL_CERT_FILE=/etc/ssl/cert.pem.

Разработка

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q && ruff check .

Планы

Компании, товары в сделках, звонки и чат-боты (imbot), события через исходящие вебхуки, OAuth-приложение для Маркетплейса Bitrix24. Предложения и PR приветствуются: см. CONTRIBUTING.md, задачи с меткой good first issue и Discussions.

English

MCP server for Bitrix24 CRM and tasks. Read-only by default; set BITRIX24_READ_ONLY=false to enable write tools (create leads, deals and tasks, move deal stages, add timeline comments).

Quick start (Claude Code):

claude mcp add bitrix24 \
  -e BITRIX24_WEBHOOK_URL="https://your-portal.bitrix24.com/rest/1/xxxxxxxx/" \
  -- uvx --from git+https://github.com/Rip-07/bitrix24-mcp bitrix24-mcp

Create the webhook under Developer resources → Other → Inbound webhook with only the scopes you need (crm, task, user). The URL is a secret.

Docker / remote agents: docker compose up -d serves Streamable HTTP at /mcp and requires Authorization: Bearer <MCP_AUTH_TOKEN>. See the settings table above for all environment variables.

Safety: webhook tokens are masked in logs and errors, method names are validated, rate-limit errors are retried with backoff, the Docker image runs as a non-root user.

Troubleshooting

• CERTIFICATE_VERIFY_FAILED on macOS with the python.org installer: run /Applications/Python 3.x/Install Certificates.command or set SSL_CERT_FILE=/etc/ssl/cert.pem.

Contributing: see CONTRIBUTING.md; questions and use cases go to Discussions.

License

MIT © Askhat Akhtanov