v0.1.0 — Bitrix24 MCP server

A universal, portable MCP server for the Bitrix24 REST API — read and write. Not tied to any one application: any MCP client can mount it (Claude Code, Claude Desktop, Cursor, Windsurf, Cline, or your own agent).

What's in it

• 100% API coverage, two ways. b24_call / b24_batch reach every REST method, and an offline catalogue of all 1930 documented methods tells an agent which method it needs and what parameters it takes (b24_method_search, b24_method_schema, b24_scope_gaps).
• 99 typed tools across 17 domains — CRM, tasks, Scrum, calendar, disk, users, workgroups, messaging, lists, catalog, orders, documents, bizproc, telephony, events, Telegram.
• Portal events, three ways: Push & Pull channel (outbound only — works behind NAT and VPN), an outgoing-webhook receiver, and a poller. Captured events land in a local SQLite archive and can be forwarded to Telegram with a filter DSL.
• Both transports: stdio (default) and stateless Streamable HTTP.
• Safety by default: a single sanitizer strips webhook URLs and tokens from every response and from httpx logs; BITRIX_READ_ONLY=1 blocks all writes.

Install

Nothing installed on the machine? Take
bitrix-mcp-0.1.0-portable-win64.zip. It carries its own Python 3.11 and every
dependency — no Python, no uv, no pip, no PyPI access needed. Unzip it, fill in
.env, run ПОДКЛЮЧИТЬ К CLAUDE.bat, restart Claude Code. Windows x64 only.

With Python already there:

pip install bitrix_mcp-0.1.0-py3-none-any.whl
export BITRIX_WEBHOOK_URL="https://<portal>/rest/<user_id>/<token>/"
bitrix-mcp                 # stdio
bitrix-mcp --http          # Streamable HTTP on 127.0.0.1:8000/mcp

Register with Claude Code:

claude mcp add -s user bitrix24 -- uv run --directory /path/to/BitrixMCP --env-file /path/to/BitrixMCP/.env bitrix-mcp

The --env-file flag matters: the package reads real environment variables and does not auto-load .env.

Bitrix quirks handled for you

Each of these was found against a production portal, by watching the result rather than trusting the API response:

• Filters are sent as a JSON body, so nested filter/select/order are not silently ignored.
• Errors are never swallowed into an empty "0 results" — a Bitrix error_description always surfaces, including the case where the error code is an empty string.
• department.get has no server-side filter at all, so filtering is done client-side.
• calendar.event.add silently drops attendees without is_meeting — it is set automatically.
• Calendar reads are trimmed: one month for one user is ~1 MB of raw JSON, so select/limit default to a compact view with an honest total and truncated flag.
• Task comments live in either the legacy forum topic or the task chat depending on the portal; the tool reads both and reports which answered.
• Scrum sprint boards: no single call moves a card. kanban.addTask only places a card that is off the board; tasks.task.update's STAGE_ID writes a visible history entry while the card stays put. The working move is deleteTask → addTask, and STAGE_ID cannot verify it.

Verified

132 offline tests, plus live verification against a production portal: reads across every reachable domain, a full task write life-cycle, both transports, the receiver fail-closed without a token, and the pull channel → store → filter → Telegram chain end to end. The published wheel was installed into a clean environment outside the repository and called the live portal from there.

The portable archive was checked the way a recipient gets it: extracted to an empty directory, run with PATH cleared so nothing on the machine could be picked up by accident — the server started and answered with all 99 tools, and the launcher registered it in Claude Code without touching the servers already configured there.

Not covered: CRM writes (the test webhook's user has no CRM access) and an end-to-end run of the outgoing-webhook receiver (needs a public URL). Both are documented in docs/USAGE.md.

Licence and security

MIT — the licence text ships inside all three artefacts
(bitrix_mcp-0.1.0.dist-info/licenses/LICENSE in the wheel, LICENSE in the
sdist and at the root of the portable archive). The portable archive also
carries CPython 3.11 under the PSF License Agreement.

Found a vulnerability? Report it privately, not in a public issue — see
SECURITY.md.

Requirements

Python ≥ 3.10, mcp[cli] 2.x. The 2.x bound is real — 2.0 replaced mcp.server.fastmcp with mcp.server.mcpserver, and this server targets the latter.

The portable archive needs none of that: the runtime it carries is the one it runs on.

Checksums

All three are built from the same commit — the wheel and the archive contain
byte-identical bitrix_mcp sources.

bitrix-mcp-0.1.0-portable-win64.zip  39,540,816 bytes
sha256  6c3c6fcc4915c38d2c15240dfcb66d2a106748ea31d8dc2dcf199b311b250b7f

bitrix_mcp-0.1.0-py3-none-any.whl       177,307 bytes
sha256  9aa1220846b32aed249ad870b93af38c636d06da9b34f5bd8752edbbcfe45900

bitrix_mcp-0.1.0.tar.gz                 242,212 bytes
sha256  26ad00bb6b7a809482bcf346e011fa3064201de23b6bfec8672fd3b30fc30c3d

Documentation is bilingual (EN/RU): README · USAGE · EVENTS · ARCHITECTURE · ROADMAP