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

---

Requirements

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

---

Installation

1. Clone the repository

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

2. Install dependencies

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

1. Log in to your Bitrix24 portal as an administrator
2. Go to Applications (left sidebar) → Webhooks
3. Click Incoming webhooks → Add webhook
4. Give it a descriptive name (e.g. Claude MCP)
5. Under Permissions, enable the scopes you need (see Access Profiles below)
6. Click Save
7. Copy the generated URL — it looks like:

   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:

Add the following entry inside "mcpServers":

{
  "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:

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:

---

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:

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

---

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

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:

1. Export the source portal config with b24_read_full_config
2. Compare it against the target with b24_compare_configs
3. 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.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes
4. 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 [email protected].