Bitrix24 MCP Bridge

Brücke zwischen Claude (MCP) und Bitrix24 CRM/Aufgaben. Gehostet auf Beget unter mcp-bitrix.karpovpartners-it.ru.

1. Warum das nötig war

Ursprünglich wurde versucht, Claude über den in Bitrix24 integrierten Connector „MCP-Verbindungen" (App aiassistant.bitrix_mcp / Schaltfläche „Б24" im Marketplace) an Bitrix24 anzubinden. Es stellte sich heraus, dass diese Funktion nicht funktioniert: Die Endpunkte /authorize, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource liefern einen nackten nginx 404, obwohl alle Einstellungen und das Abonnement in Ordnung sind. Das ist ein Bug/Feature-Fehler auf Seiten von Bitrix24, kein Konfigurationsfehler.

Als Workaround wurde ein eigener MCP-Server („Brücke") geschrieben, der:

• nimmt MCP-Anfragen von Claude über das Streamable-HTTP-Protokoll entgegen;

• übersetzt sie in Aufrufe der normalen Bitrix24-REST-API über einen eingehenden Webhook (in Bitrix24 mit Rechten nur für CRM + Aufgaben erstellt);

• gibt das Ergebnis als MCP-Tool-Antworten an Claude zurück.

Related MCP server: fast-bitrix24-mcp

2. Architektur und Dateien

Welche Tools sind in Claude verfügbar

• bitrix24_call – direkter Aufruf beliebiger Methoden crm.*, task.*, tasks.*, user.current, profile (Escape-Luke).

• bitrix24_list_crm / bitrix24_get_crm / bitrix24_add_crm / bitrix24_update_crm – Liste/Lesen/Erstellen/Aktualisieren von CRM-Einträgen (lead, deal, contact, company).

• bitrix24_list_tasks / bitrix24_add_task / bitrix24_update_task / bitrix24_complete_task – Arbeiten mit Aufgaben.

Der Server beschränkt die aufgerufenen Bitrix24-Methoden strikt auf die Präfixe crm., task., tasks., user.current, profile (siehe ALLOWED_METHOD_PREFIXES in server.mjs) – das ist ein Schutz für den Fall, dass der Webhook jemals umfangreichere Rechte erhält.

3. Authentifizierung / Sicherheit

Benutzerdefinierte MCP-Connectors in der Claude-Oberfläche haben kein Feld für beliebige HTTP-Header – nur URL (plus optional OAuth Client ID/Secret). Deshalb ist das Geheimnis statt im Authorization-Header in den URL-Pfad eingebettet:

https://mcp-bitrix.karpovpartners-it.ru/mcp/<секрет>

Das Geheimnis und die Adresse des Bitrix24-Webhooks werden nur in der produktiven .htaccess auf dem Server und in einer privaten Kopie beim Projektinhaber gespeichert – sie sind absichtlich nicht in dieses Repository eingecheckt (siehe .gitignore). Jeder, der das Geheimnis aus der URL erfährt, erhält Zugriff auf CRM und Aufgaben von Bitrix24 im Rahmen der Webhook-Rechte.

4. So funktioniert es Schritt für Schritt

1. Claude öffnet den MCP-Connector → POST an /mcp/<secret> mit dem Body {"method":"initialize", ...}.

2. Die Express-Route in server.mjs erstellt einen neuen McpServer (StreamableHTTPServerTransport, sessionIdGenerator: undefined – Server ohne Session-Speicherung, jede Anfrage ist unabhängig).

3. Claude ruft tools/list auf, dann tools/call mit einem bestimmten Tool (z.B. bitrix24_list_crm).

4. server.mjs ruft bitrixCall(method, params) auf, das ein fetch() auf https://<portal>.bitrix24.ru/rest/<id>/<webhook>/<method>.json ausführt.

5. Die Antwort von Bitrix24 wird in das MCP-Format verpackt und an Claude zurückgesendet.

5. Bereitstellung von Grund auf

1. Eingehenden Webhook in Bitrix24 erstellen: Einstellungen → Entwicklern → Sonstiges → Eingehender Webhook. Rechte – mindestens CRM + Aufgaben.

2. Repository auf den Server klonen, in das Website-Verzeichnis (public_html Ihrer Domain/Subdomain).

3. npm install in diesem Verzeichnis (installiert express, zod, @modelcontextprotocol/sdk, undici).

4. .htaccess.example in .htaccess kopieren und die echten BITRIX_WEBHOOK_URL und MCP_PATH_SECRET eintragen.

5. Auf Beget: mkdir tmp && touch tmp/restart.txt – Passenger-Befehl zum Neustart der Anwendung nach Codeänderungen.

6. Im Beget-Panel: „Websites" → bei der gewünschten Website → „⋮" → „Domain anhängen" – ohne diesen Schritt versucht Apache nicht einmal, Ihren Code zu erreichen (siehe Abschnitt 6.2 – leicht zu vergessen, Fehler nicht offensichtlich).

6. Probleme bei der Bereitstellung auf Beget und deren Lösungen

Debug-Log – nützlich bei erneuter Bereitstellung auf Beget oder einem anderen Shared-Hosting mit altem Node.js.

6.1. Node.js auf Beget – Version 16.20.2, zu alt

Auf Beget (Ubuntu 18.04, glibc 2.27) lassen sich offizielle Node-18+-Builds nicht starten (GLIBC_2.28' not found). Wir mussten bei Node 16.20.2 bleiben und die in Node 16 fehlenden globalen Objekte manuell bereitstellen, die moderne Abhängigkeiten (@modelcontextprotocol/sdk, Express 5) benötigen:

• fetch, Headers, Request, Response – über das Paket undici.

• crypto (Web Crypto API, crypto.randomUUID()) – über das eingebaute node:crypto (webcrypto).

• ReadableStream, WritableStream, TransformStream – über das eingebaute node:stream/web.

• structuredClone, MessageChannel/MessagePort – für alle Fälle, über node:v8 und node:worker_threads.

All dies steht ganz am Anfang von server.mjs, vor dem Import von Express und MCP SDK (über await import(...) statt eines normalen import am Dateianfang – siehe nächster Punkt, warum).

6.2. Domain war nicht an das Website-Verzeichnis „angehängt"

Nach dem Hochladen des Codes auf den Server lieferte die Website die Beget-eigene Seite „Domain ist nicht an das Verzeichnis auf dem Server gebunden" statt der Anwendung aus. Es reicht nicht, einfach einen Website-Ordner zu erstellen und Dateien hineinzuladen – die Domain muss separat über das Panel „angehängt" werden: Websites → gewünschte Website → ⋮ → „Domain anhängen". Ein nicht offensichtlicher Schritt, den man leicht übersieht.

6.3. ERR_REQUIRE_ESM: Passenger kann keine ES-Module laden

Passenger auf Beget (alte Version, passenger40) startet die Startdatei über require(), und require() in Node kann grundsätzlich keine ES-Module laden (import/export, type: module in package.json). server.mjs verwendet await auf oberster Dateiebene – das ist nur in einem ES-Modul möglich.

Lösung: In package.json gibt es kein "type": "module" (standardmäßig ist .js CommonJS), der Code selbst liegt in einer Datei mit der Erweiterung .mjs (die Erweiterung .mjs ist immer ein ES-Modul, unabhängig von package.json), und als Einstiegspunkt für Passenger dient app.js – eine winzige CommonJS-Datei:

// app.js
import('./server.mjs').catch((err) => {
  console.error('Failed to start server:', err);
  process.exit(1);
});

require() lädt app.js problemlos (es ist normales CommonJS), und darin kann ein dynamisches import() (das ist eine Funktion, keine Deklaration) das ES-Modul server.mjs asynchron laden.

6.4. Geheimnis im URL-Pfad

MCP_PATH_SECRET – eine zufällige Zeichenfolge (z.B. secrets.token_urlsafe(32) in Python oder crypto.randomUUID() + crypto.randomUUID() in der Browserkonsole). Wenn das Geheimnis neu ausgestellt werden muss – ein neues generieren und in der .htaccess auf dem Server sowie in den Connector-Einstellungen in Claude aktualisieren.

7. So verbinden Sie es in Claude

1. claude.ai → Einstellungen → Connectors → Add custom connector.

2. Name: Bitrix24 (beliebig).

3. Remote MCP server URL: https://mcp-bitrix.karpovpartners-it.ru/mcp/<secret>

4. OAuth Client ID / Secret – leer lassen, sie werden nicht benötigt (die Autorisierung ist bereits in der URL eingebettet).

5. Speichern, Connector im Chat aktivieren.

8. Offene Frage – nativer MCP-Connector von Bitrix24

Es lohnt sich, den Bitrix24-Support über den defekten nativen MCP-Connector („Б24" im Marketplace) zu informieren: /authorize und die standardmäßigen OAuth-Discovery-Endpunkte liefern einen nackten nginx 404 bei aktivierten Einstellungen und aktivem Abonnement. Wenn/falls Bitrix24 das behebt, kann man auf den offiziellen Connector umsteigen – oder diese Brücke behalten, sie funktioniert ebenfalls und bietet mehr Kontrolle (z.B. Einschränkung der Methoden auf CRM+Aufgaben direkt im Code).