An MCP server for Bitrix24: CRM deals and tasks in an agent's hands

When people search for a Bitrix24 MCP server, they usually mean one of two different things. The first is a server that helps an agent write correct code against the Bitrix24 REST API. The second is a server through which the agent reads deals and creates tasks in your portal. Officially, Bitrix24 has only the first. Below we explain the difference, show how to build the second with minimal rights, and how to connect it to an agent.

The Bitrix24 facts come from the official documentation at apidocs.bitrix24.com as of October 18, 2026. Interface item names there are for the English version and may read differently in the Russian one, so check against your own portal.

What the official Bitrix24 MCP gives you

The docs describe a b24-dev-mcp server at https://mcp-dev.bitrix24.com/mcp. It runs over the Streamable HTTP protocol (no legacy SSE) and is open without authorization. The documentation says it plainly: the server serves up-to-date REST API documentation, but it has no access to Bitrix24 data and does not execute method calls.

Its purpose is different: to stop the model from inventing nonexistent REST methods and sending you to dead links. The server has five tools: documentation search (bitrix-search), a method description by exact name (bitrix-method-details), an event description (bitrix-event-details), an article (bitrix-article-details) and app development material (bitrix-app-development-doc-details).

Connecting to Claude Code, per the Bitrix24 docs, takes one command:

claude mcp add --transport http b24-dev-mcp https://mcp-dev.bitrix24.com/mcp
claude mcp list

If you are writing an integration, connect it first: the code will be more accurate. More on working with MCP in Claude Code is in MCP servers in Claude Code↗.

When you need your own server

For a task like "show deals at the Invoice stage and create a task for the manager", the agent needs access to data. For that you write your own wrapper MCP server: the agent calls a list_deals tool, the server makes a REST request to the portal and returns the result. The key piece here is an inbound webhook.

The webhook and rights: the main place to go wrong

An inbound webhook is a secret URL through which an external system calls portal methods. The documentation stresses two facts.

First: requests run with the rights of the employee who created the webhook, and only within the selected scopes. If you create the webhook as an administrator, the agent gets administrator rights even if you ticked a single scope.

Second: the secret code must not be shown or embedded in public code.

That gives you this order of actions:

1. Create a dedicated user for the agent with a limited role: sees only the needed pipelines, cannot delete.
2. If webhook creation is disabled, an administrator allows it in the security settings (Settings → Bitrix24 settings → Security → Bitrix24 integrations, the field Who can create inbound webhooks).
3. Sign in as that user, open Applications → Developer resources, then Common use cases → Other → Inbound webhook.
4. In the Permission settings block tick only crm and task. The docs say the required scope for each method is given on that method's page.
5. If possible set an expiry for the webhook: the docs mention it can be limited by date.

The webhook URL looks like https://portal.bitrix24.com/rest/<user id>/<secret code>/method.json. Save it in the B24_WEBHOOK environment variable without the method name.

A minimal Python server

The example uses the mcp package (the FastMCP class) and requests. The mcp library API evolves, so check its documentation if the import does not match.

import os
import requests
from mcp.server.fastmcp import FastMCP

WEBHOOK = os.environ["B24_WEBHOOK"].rstrip("/")
ALLOW_WRITE = os.environ.get("B24_ALLOW_WRITE") == "1"
mcp = FastMCP("bitrix24")


def call(method: str, params: dict) -> dict:
    r = requests.post(f"{WEBHOOK}/{method}.json", json=params, timeout=30)
    r.raise_for_status()
    data = r.json()
    if "error" in data:

What is deliberate here. The fields in select are listed explicitly: the agent does not need all 100 deal fields, and extra fields cost tokens. Reading and writing are separated, and writing is off by default. No delete method is implemented at all: what is not described as a tool, the agent cannot call.

Connecting to the agent

In Claude Code:

claude mcp add --env B24_WEBHOOK=https://portal.bitrix24.com/rest/7/secret --transport stdio bitrix24 -- python /path/to/b24_server.py

Claude Code works through the variables ANTHROPIC_BASE_URL=https://api.zukko.pro (without /v1), ANTHROPIC_AUTH_TOKEN=fetch_... and ANTHROPIC_MODEL=claude-sonnet-5-5; see the Claude Code documentation↗. In opencode the same server is declared with an mcp block with "type": "local" and the command ["python", "/path/to/b24_server.py"], and the Zukko address there carries /v1.

REST limits and what to do about them

In cloud Bitrix24 a request must finish within 60 seconds. Request rate is limited on a "leaky bucket" principle: per the docs, on the Enterprise plan the counter drops by 5 per second and blocking starts at 250, on other plans 2 per second and 50. On excess you get status 503 and the code QUERY_LIMIT_EXCEEDED. For an agent this means: do not ask "export all deals for three years" in one prompt, bound your queries and use batch (up to 50 calls in one HTTP request) if you implement bulk operations. The server should return a limit error to the model as clear text rather than stay silent.

What not to give the agent

• Administrator rights and deletion. A dedicated user and the absence of a delete tool cover this.
• Reading fields you do not need: customers' phones and emails when the task is about stages.
• Trust in text from the CRM. A comment on a deal or a customer's note can contain a phrase addressed to the model. Treat everything a tool returns as data, not a command, and keep confirmation on writes.
• A shared key for everyone. For the model, create a separate Zukko key with a daily limit on the API keys page↗.

What it costs

Say that in a day the agent answers 30 CRM questions, each using 20,000 input tokens and 1,500 output tokens. Total: 600,000 input and 45,000 output tokens. Zukko prices on October 18, 2026, $ per 1M tokens, cache ignored:

• claude-sonnet-5-5 (0.4 / 2): 0.6 × 0.4 + 0.045 × 2 = 0.24 + 0.09 = $0.33.
• gpt-6.1-sol (0.27 / 1.32): 0.6 × 0.27 + 0.045 × 1.32 = 0.162 + 0.0594 ≈ $0.22.
• deepseek-v4.1-flash (0.013 / 0.038): 0.6 × 0.013 + 0.045 × 0.038 = 0.0078 + 0.00171 ≈ $0.01.

Which model calls your tools more reliably, test on your own data. List and prices: GET https://api.zukko.pro/v1/models. For the broader picture of integrating with a portal see a neural network in Bitrix24 via webhooks↗.

FAQ

Can the official Bitrix24 MCP read my deals?

No. It serves documentation only and does not touch portal data. For data you need your own server or another integration method.

Is a webhook enough for such a server?

For personal and internal scenarios where requests run on behalf of one user, yes. If the solution will serve different users or go to the marketplace, you need an app with OAuth 2.0, local or marketplace.

Where do I keep the webhook URL?

In an environment variable or a secrets manager, not in a repository or a prompt. If it leaks, recreate the webhook.

Can I give the agent write access to the CRM?

You can, but deliberately: separate write tools, confirmation of every call and minimal user rights. Better not to allow deletion at all.