Bitrix24 MCP Server is a Model Context Protocol (MCP) server that connects Claude to your Bitrix24 portal via an incoming webhook. Once configured, Claude can read and write CRM records, manage tasks, browse disks, send notifications, query the product catalog, run business processes, and more in natural conversation. The project is built and maintained by Bit2Beat (a team of Bitrix24 experts).
Prerequisites
Using this server requires the following: Node.js 18 or higher; Claude Desktop or Claude Code; a Bitrix24 incoming webhook URL.
Installation and Configuration
- Clone the repository (git clone). 2. Install dependencies (npm install). 3. Create a Bitrix24 Webhook: administrator privileges are required; only Bitrix24 portal administrators can create incoming webhooks, which is a platform security restriction—a webhook is equivalent to system-level credentials and may carry broader permissions than a regular user session. Log in to the Bitrix24 portal as an administrator, go to "Applications" in the left sidebar → "Webhooks", click "Incoming webhooks" → "Add webhook", give it a descriptive name (for example Claude MCP), enable the required scopes under "Permissions" (see the Access Profiles below), and copy the generated URL, which has a format similar to:https://your-portal.bitrix24.com/rest/1/abc123xyz/ . This URL is B24_DEFAULT_WEBHOOK; keep it private—it grants API access to the portal. If you need to edit the webhook or add more scopes after the initial setup: Applications → Webhooks → Incoming webhooks → click the webhook name.
- Configure Claude Desktop: open the Claude Desktop configuration file and add the corresponding entry inside "mcpServers". Windows note: use forward slashes (/) or escaped backslashes (\) in paths.
- Restart Claude Desktop: after saving the configuration file, restart Claude Desktop, and you should see the Bitrix24 tools in the tools panel.
Access Profiles
Bitrix24 webhooks use scopes to control which modules can be accessed. Each scope unlocks a set of API methods—but within a scope, all operations (read and write) are allowed, and there is no built-in "read-only" flag at the scope level. The practical way to limit what Claude can do is to combine the right set of scopes. The following three ready-made configurations cover the most common use cases:
Profile 1 — Structure Inspector (no access to business data): use this when you want Claude to understand the portal configuration (pipelines, stages, custom fields, automation) but not access any actual records (no deals, contacts, tasks). Suitable for: consultants auditing portal settings, or developers mapping out the CRM before building an integration. Can do: b24_read_full_config, b24_read_pipelines, b24_read_custom_fields, b24_read_entity_types, b24_read_automations, b24_read_product_catalog, b24_compare_configs, b24_users_list, b24_departments_list. Cannot do: read or write deals, contacts, tasks, disk files, chats, or calendars. Note: pipeline and custom field data are accessed internally via the crm module. If you also want to inspect the CRM structure (stages, field names), you can add crm to this configuration—but note that this will also enable read access to CRM records.
Profile 2 — Read-only operations: use when you want Claude to read business data but not create or modify anything. Suitable for: reports, analysis, answering questions about pipeline status or task progress. Important reminder: Bitrix24 scopes do not distinguish between read and write at the API level. The crm scope enables both crm.deal.list (read) and crm.deal.add (write). Scopes alone cannot enforce read-only access. There are two ways to achieve a true read-only profile: Trust-based: enable only the scopes below and instruct Claude not to modify data; Claude will follow the instructions, but there is no technical enforcement. Enforcement-based: run a separate MCP server instance that registers only read tools; this requires a small code change and is planned as a future feature (B24_PROFILE=readonly).
Profile 3 — Full access: use when you want Claude to act as a complete Bitrix24 assistant — reading, writing, sending messages, managing files, and everything else. When a requested operation requires a scope that the Webhook has not enabled, Claude will report it gracefully, so you can always start with fewer scopes and add more later.
Available tools
Connection and basics: b24_test_connection (verify the Webhook and confirm portal information and user permissions). CRM: b24_crm_list (list CRM records with filtering and automatic pagination), b24_crm_get (get a single CRM record by ID), b24_crm_create (create a CRM record), b24_crm_update (update a CRM record), b24_crm_delete (delete a CRM record), b24_crm_fields (list all available fields for an entity, including standard and custom), b24_crm_timeline_add (add a comment or activity to a CRM record's timeline). Tasks: b24_tasks_list (list tasks with filtering), b24_tasks_get (get full task details), b24_tasks_create (create a task), b24_tasks_update (update a task), b24_tasks_complete (mark a task as complete). Users and departments: b24_users_list (list active users), b24_departments_list (list departments with hierarchy). Disk: b24_disk_storages (list available storages), b24_disk_folder_list (browse folder contents), b24_disk_file_get (get file information and download URL), b24_disk_file_upload (upload a file to a folder). Calendar: b24_calendar_list (list calendar events), b24_calendar_create (create a calendar event). Communication and collaboration: b24_chat_send (send a private or group chat message), b24_notify_send (send a personal notification), b24_feed_post (post to the activity stream), b24_groups_list (list workgroups and projects). Business processes: b24_bizproc_list (list active workflow instances), b24_bizproc_start (start a business process on a record). Telephony: b24_telephony_calls (query the call history log). Product catalog: b24_products_list (list catalog products), b24_products_get (get product details), b24_products_create (create a product), b24_products_update (update a product), b24_products_sections (list catalog sections). Configuration management: b24_read_full_config (export the full portal configuration as JSON), b24_read_entity_types (read CRM and SPA entity types), b24_read_pipelines (read pipelines and their stages), b24_read_custom_fields (read custom fields for all CRM entities), b24_read_automations (read automation rules by stage), b24_read_product_catalog (read the product catalog structure), b24_compare_configs (compare two portal configuration JSON files), b24_apply_config (apply an exported configuration to a target portal), b24_save_user_mapping (generate a user ID mapping between two portals). Generic call: b24_call (directly call any Bitrix24 REST API methods), b24_batch (execute multiple API calls in a single HTTP request).
Usage Examples
After configuration is complete, you can ask Claude questions such as: "Show all open deals assigned to María," "Create a task for Tadeo to review the contract by Friday," "What calls came in from Company X this week?", "Export this portal's complete CRM configuration as JSON," "Compare this portal's pipeline configuration with the configuration in config_backup.json."
Rate Limiting and Retries
The HTTP client enforces a minimum delay of 500 milliseconds between requests to comply with Bitrix24's rate limits, and automatically retries on 429 Too Many Requests and timeout errors (up to 3 retries with exponential backoff).
Configuration Migration
This server includes tools for Bitrix24 consultants and partners who need to replicate portal configurations across multiple instances: use b24_read_full_config to export the source portal configuration; use b24_compare_configs to compare it with the target; use b24_apply_config to apply it to the target. This workflow covers pipelines, stages, custom fields, currencies, SPA types, automation, and product catalogs.
Contributing and Support
Contributions are welcome; please open an issue first to discuss what you want to change. Process: Fork the repository; create a feature branch (git checkout -b feature/your-feature); commit your changes; open a pull request. Bit2Beat is a Bitrix24 specialist company that builds integrations, automation, and AI-driven tools on the Bitrix24 platform. If you need help implementing this MCP server or building custom Bitrix24 integrations, you can send an email to info@bit2beat.com .
Limitations
The only limitations explicitly mentioned in the materials: Bitrix24 scopes do not distinguish between read and write at the API level, and the scope itself cannot enforce read-only; true read-only requires a separate instance that registers only read tools, and this feature (B24_PROFILE=readonly) is still planned. Other information such as fees, pricing, and platform support scope is not yet provided in the materials.