Bitrix24 MCP Server

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 your disk, send notifications, query the product catalog, run business processes, and much more — all from natural conversation.

Built and maintained by Bit2Beat — Bitrix24 specialists.

Features

Area	What Claude can do
CRM	List, get, create, update, and delete deals, contacts, companies, leads, and Smart Process items. Add timeline comments.
Tasks	List, get, create, update, and complete tasks.
Users & Departments	List active users and the organizational structure.
Disk	Browse storages and folders, get file info and download links, upload files.
Calendar	List and create calendar events.
Chat & Notifications	Send private messages and personal notifications.
Live Feed	Post messages to the activity feed.
Groups	List workgroups and projects.
Business Processes	List active workflows and start new ones.
Telephony	Query the call history log.
Product Catalog	List, get, create, and update products and sections.
Configuration	Export the full portal config (pipelines, stages, custom fields, automations) to JSON, compare two configs, and apply one config to another portal.
Raw API	Call any Bitrix24 REST method directly, including batch requests.

Requirements

Node.js 18 or higher
Claude Desktop or Claude Code
A Bitrix24 incoming webhook URL

Installation

1. Clone the repository

hljs language-bash

git clone https://github.com/bit2beat/bitrix24-mcp.git
cd bitrix24-mcp

2. Install dependencies

hljs language-bash

npm install

3. Create your Bitrix24 webhook

Administrator required. Only a Bitrix24 portal administrator can create incoming webhooks. This is a platform security restriction — webhooks act as system-level credentials and can carry broader permissions than a regular user session.

Step-by-step

Log in to your Bitrix24 portal as an administrator
Go to Applications (left sidebar) → Webhooks
Click Incoming webhooks → Add webhook
Give it a descriptive name (e.g. Claude MCP)
Under Permissions, enable the scopes you need (see Access Profiles below)
Click Save
Copy the generated URL — it looks like:
hljs language-bash
```
https://your-portal.bitrix24.com/rest/1/abc123xyz/
```
This URL is your B24_DEFAULT_WEBHOOK. Keep it private — it grants API access to your portal.

Where to find it later

If you need to edit the webhook or add more scopes after the initial setup:

Applications → Webhooks → Incoming webhooks → (click your webhook name)

4. Configure Claude Desktop

Open your Claude Desktop configuration file:

OS	Path
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following entry inside "mcpServers":

hljs language-json

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["C:/full/path/to/bitrix24-mcp/index.js"],
      "env": {
        "B24_DEFAULT_WEBHOOK": "https://your-portal.bitrix24.com/rest/1/your-token/"
      }
    }
  }
}

Windows note: use forward slashes (/) or escaped backslashes (\\) in the path.

5. Restart Claude Desktop

After saving the config file, restart Claude Desktop. You should see the Bitrix24 tools available in the tools panel.

Access Profiles

Bitrix24 webhooks use scopes to control which modules are accessible. Each scope unlocks a set of API methods — but within a scope, all operations (read and write) are permitted. 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. Below are three ready-made profiles that cover the most common use cases.

Profile 1 — Structure Inspector (no business data)

Use this when you want Claude to understand the portal's configuration — pipelines, stages, custom fields, automations — without access to any actual records (no deals, no contacts, no tasks).

Ideal for: consultants auditing a portal setup, or developers mapping the CRM before building an integration.

Scopes to enable:

Scope	What it unlocks
`user`	Read user list (needed to resolve assignee names)
`department`	Read department structure
`bizproc`	Read automation rules and business processes
`catalog`	Read product catalog structure

What Claude 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

What Claude cannot do: read or write deals, contacts, tasks, disk files, chat, or calendar.

Note: Pipeline and custom field data is accessed through the crm module internally. If you also want to inspect CRM structure (stages, field names), add crm to this profile — but be aware that this also enables read access to CRM records.

Profile 2 — Read-Only Operations

Use this when you want Claude to read business data but not create or modify anything.

Ideal for: reporting, analysis, answering questions about pipeline status or task progress.

Important caveat: 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.

To achieve a true read-only profile you have two options:

Trust-based: Enable only the scopes below and instruct Claude not to modify data. Claude will follow the instruction, but there is no technical enforcement.
Enforcement-based: Run a separate instance of this MCP server that only registers read tools. This requires a small code change and is planned as a future feature (B24_PROFILE=readonly).

Recommended scopes for a read-leaning profile:

Scope	What it unlocks
`crm`	Read (and write) CRM records
`task`	Read (and write) tasks
`user`	Read users
`department`	Read departments
`catalog`	Read product catalog
`bizproc`	Read automations
`telephony`	Read call history

Profile 3 — Full Access

Use this when you want Claude to operate as a full Bitrix24 assistant — reading, writing, sending messages, managing files, and everything in between.

All scopes:

Scope	Enables
`crm`	CRM records (deals, contacts, companies, leads, SPAs)
`task`	Tasks
`user`	Users
`department`	Departments
`disk`	Disk / file storage
`calendar`	Calendar events
`im`	Chat messages and notifications
`bizproc`	Business processes and automations
`catalog`	Product catalog
`telephony`	Call history

Claude will gracefully report when a requested action requires a scope that is not enabled on the webhook, so you can always start with fewer scopes and add more later.

Available Tools

Click to expand full tool list (40 tools)

Connection

b24_test_connection — Verify the webhook and confirm portal info and user permissions.

CRM

b24_crm_list — List CRM records with filters and automatic pagination.
b24_crm_get — Get a single CRM record by ID.
b24_crm_create — Create a new CRM record.
b24_crm_update — Update an existing CRM record.
b24_crm_delete — Delete a CRM record.
b24_crm_fields — List all available fields for an entity (standard + custom).
b24_crm_timeline_add — Add a comment or activity to a CRM record's timeline.

Tasks

b24_tasks_list — List tasks with filters.
b24_tasks_get — Get full task detail.
b24_tasks_create — Create a new task.
b24_tasks_update — Update an existing task.
b24_tasks_complete — Mark a task as complete.

Users & 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 a folder's contents.
b24_disk_file_get — Get file info 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

b24_chat_send — Send a private or group chat message.
b24_notify_send — Send a personal notification.
b24_feed_post — Post to the Live Feed.
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 detail.
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 complete portal configuration to 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 across 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 config JSON files.
b24_apply_config — Apply an exported config to a target portal.
b24_save_user_mapping — Generate a user ID mapping between two portals.

Raw API

b24_call — Call any Bitrix24 REST API method directly.
b24_batch — Execute multiple API calls in a single HTTP request.

Usage Examples

Once configured, you can ask Claude things like:

"Show me all open deals assigned to María"

"Create a task for Tadeo to review the contract, due Friday"

"What calls came in from company X this week?"

"Export the full CRM configuration of this portal to JSON"

"Compare this portal's pipeline config with the one in config_backup.json"

Architecture

hljs language-scss

Claude (Claude Desktop / Claude Code)
        │  MCP protocol (stdio)
        ▼
   index.js  (MCP server — 40 tools)
        │
   src/tools/      ← one file per functional area
   src/bitrix24/   ← HTTP client with rate limiting & retry
   src/utils/      ← pagination, rate limiter, user mapping
        │
        ▼
  Bitrix24 REST API  (via incoming webhook)
        │
        ▼
   Your Bitrix24 Portal

The HTTP client enforces a 500 ms minimum delay between requests to respect Bitrix24's rate limits, and retries automatically on 429 Too Many Requests and timeout errors (up to 3 retries with exponential backoff).

Configuration Migration

This server includes tools designed for Bitrix24 consultants and partners who need to replicate portal configurations across multiple instances:

Export the source portal config with b24_read_full_config
Compare it against the target with b24_compare_configs
Apply it to the target with b24_apply_config

This workflow covers pipelines, stages, custom fields, currencies, SPA types, automations, and the product catalog.

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit your changes
Open a pull request

License

MIT

About Bit2Beat

Bit2Beat is a Bitrix24 specialist firm. We build integrations, automations, and AI-powered tools on top of the Bitrix24 platform.

If you need help implementing this MCP server or building custom Bitrix24 integrations, feel free to reach out at info@bit2beat.com.

bitrix24-mcp