b24-mcp

A local MCP server for Bitrix24. It gives your AI agent fresh data from your portal — calendar, tasks and their discussions, chats, collab projects, AI call analyses, and people cards.

Read-only. Works with any portal — cloud or on-premise — through your personal inbound webhook.

Why bother if the agent can already do HTTP

The agent can call REST itself. But then:

• on every request it assembles the URL, remembers method names and API versions, parses the response;

• the token passes through its environment on every call;

• nothing stops it from calling a method that changes the portal.

The server removes this: the agent calls a business operation (tasks_list, task_chat), while transport, versions, pagination, and normalization live inside. Only read operations and only the listed ones are exposed — raw REST is not exposed at all.

Related MCP server: Bitrix24 MCP Bridge

What it can do (14 tools)

Responses are normalized: lists come as {items, count, limit}, markup is stripped, limits are clamped.

Installation

Python 3.11+ is required.

git clone <этот-репозиторий> b24-mcp && cd b24-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e .

Configuration

1. Issue an inbound webhook on your portal. Developer section: Applications → Developers → Other → Inbound webhook.

Scopes used by the server:

Fewer scopes — less risk. Start without call, add it when you need calls.

2. Put the webhook in .env:

cp .env.example .env
chmod 600 .env          # сервер откажется читать файл, доступный другим

B24_WEBHOOK=https://<твой-портал>/rest/<число>/<токен>/
B24_USER_ID=<твой id>   # необязательно: определится сам через user.current

3. Connect it to your MCP client. Example for Claude Code (~/.claude.json):

{
  "mcpServers": {
    "b24": {
      "command": "/абсолютный/путь/b24-mcp/.venv/bin/python",
      "args": ["-m", "b24_mcp.server"],
      "env": { "B24_MCP_ENV": "/абсолютный/путь/b24-mcp/.env" }
    }
  }
}

Restart the client and ask the agent: "check the connection to the portal" — it will call whoami.

Security

• The token lives in .env with 600 permissions. The server checks permissions at startup and refuses to work if the file is readable by others.

• The token never appears in tool responses, logs, or error texts. The operation name and time are logged, not the URL.

• Read-only. The client is created with write methods blocked at the transport level, and only the listed operations are exposed. Even a bug in a tool's code will not create a task or send a message.

• Honest boundary: this removes the class of "secret accidentally leaked into command output," but it does not take the shell away from the agent. If it has filesystem access, it can still read .env — just like any process running under your user.

• Only what the webhook owner is a participant in is visible. The server cannot reach other people's private chats and events.

• If the token leaks — revoke the webhook on the portal and issue a new one; you only need to change .env.

Development

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q --asyncio-mode=auto

Tests run without a network. They pin the tool list (a new one will not appear silently), the read-only barrier, the normalization contract, and the portal response shapes — including the ones that are easy to miss.

Two contract pitfalls that cost debugging time (covered by tests):

• The call transcript is in the transcription field (not transcript), the summary comes in segments ({segments: [{title, summary}]}), agreements and tasks are under the agreement / actionItem keys, not text. A miss gives a silently empty response, not an error.

• A call participant is identified by the userId field, not id. Reading id will return None — and the participant cannot be linked to a person.

Boundaries

The server deliberately does not do:

• write operations — does not create tasks, send messages, or change the portal;

• heavy runs — a full sweep of all correspondence over a month, exporting quarterly reports, summarizable traversals with checkpoints. A tool call lives within a single agent turn: there is a time ceiling and nowhere to save progress. Such tasks are solved by a separate script, not an MCP tool.

License

MIT.