Bitrix24 MCP Bridge

Puente entre Claude (MCP) y Bitrix24 CRM/Tareas. Desplegado en el hosting Beget en la dirección mcp-bitrix.karpovpartners-it.ru.

1. Por qué fue necesario

Inicialmente intentamos conectar Claude a Bitrix24 mediante el conector integrado en Bitrix24 «conexiones MCP» (aplicación aiassistant.bitrix_mcp / botón «B24» en el marketplace). Resultó que esta función no funciona: los endpoints /authorize, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource devuelven un nginx 404 puro, aunque todos los ajustes y la suscripción estén en orden. Es un bug/función inacabada del lado de Bitrix24, no un fallo de configuración.

Como solución alternativa, se escribió un servidor MCP propio («el puente») que:

• recibe solicitudes MCP de Claude mediante el protocolo Streamable HTTP;

• las traduce en llamadas al REST API normal de Bitrix24 a través de un webhook de entrada (creado en Bitrix24 con permisos solo para CRM + Tareas);

• devuelve el resultado a Claude en forma de respuestas de herramientas MCP.

Related MCP server: fast-bitrix24-mcp

2. Arquitectura y archivos

Qué herramientas (tools) están disponibles en Claude

• bitrix24_call: invoca directamente cualquier método de crm.*, task.*, tasks.*, user.current, profile (vía de escape).

• bitrix24_list_crm / bitrix24_get_crm / bitrix24_add_crm / bitrix24_update_crm: lista/lectura/creación/actualización de registros CRM (lead, deal, contact, company).

• bitrix24_list_tasks / bitrix24_add_task / bitrix24_update_task / bitrix24_complete_task: trabajo con tareas.

El servidor limita estrictamente los métodos de Bitrix24 invocables a los prefijos crm., task., tasks., user.current, profile (ver ALLOWED_METHOD_PREFIXES en server.mjs); es una protección por si el webhook llegara a tener permisos más amplios en el futuro.

3. Autenticación / seguridad

Los conectores MCP personalizados en la interfaz de Claude no tienen campo para cabeceras HTTP arbitrarias: solo URL (+ opcionalmente OAuth Client ID/Secret). Por eso, en lugar de la cabecera Authorization, el secreto está incrustado en la ruta de la URL:

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

El secreto y la dirección del webhook de Bitrix24 se almacenan solo en el .htaccess de producción del servidor y en una copia privada del propietario del proyecto: no se ha hecho deliberadamente ningún commit de ellos en este repositorio (ver .gitignore). Cualquiera que descubra el secreto de la URL obtendrá acceso al CRM y a las tareas de Bitrix24 dentro de los permisos del webhook.

4. Cómo funciona paso a paso

1. Claude abre el conector MCP → POST a /mcp/<секрет> con el cuerpo {"method":"initialize", ...}.

2. La ruta Express en server.mjs crea un nuevo McpServer (StreamableHTTPServerTransport, sessionIdGenerator: undefined — servidor sin persistencia de sesión, cada solicitud es independiente).

3. Claude llama a tools/list y luego a tools/call con la herramienta concreta (por ejemplo, bitrix24_list_crm).

4. server.mjs llama a bitrixCall(method, params), que hace fetch() a https://<портал>.bitrix24.ru/rest/<id>/<вебхук>/<метод>.json.

5. La respuesta de Bitrix24 se envuelve en formato MCP y regresa a Claude.

5. Despliegue desde cero

1. Crear un webhook entrante en Bitrix24: Configuración → Desarrolladores → Otro → Webhook entrante. Permisos: mínimo CRM + Tareas.

2. Clonar el repositorio en el servidor, en el directorio del sitio (public_html del dominio/subdominio).

3. npm install en ese directorio (instalará express, zod, @modelcontextprotocol/sdk, undici).

4. Copiar .htaccess.example a .htaccess y escribir los valores reales de BITRIX_WEBHOOK_URL y MCP_PATH_SECRET.

5. En Beget: mkdir tmp && touch tmp/restart.txt — comando de Passenger para reiniciar la aplicación después de cualquier cambio en el código.

6. En el panel de Beget: «Sitios» → en el sitio correspondiente → «⋮» → «Vincular dominio»; sin este paso, Apache ni siquiera intenta llegar a su código (ver sección 6.2: es fácil olvidarlo, es un error poco evidente).

6. Problemas encontrados al desplegar en Beget y cómo los resolvimos

Registro de depuración: útil para futuros despliegues en Beget u otro hosting compartido con Node.js antiguo.

6.1. Node.js en Beget: versión 16.20.2, demasiado antigua

En Beget (Ubuntu 18.04, glibc 2.27), las compilaciones oficiales de Node 18+ no se ejecutan (GLIBC_2.28' not found). Tuvimos que quedarnos en Node 16.20.2 y añadir manualmente los objetos globales que faltan en Node 16 y que necesitan las dependencias modernas (@modelcontextprotocol/sdk, Express 5):

• fetch, Headers, Request, Response — mediante el paquete undici.

• crypto (Web Crypto API, crypto.randomUUID()) — mediante el módulo integrado node:crypto (webcrypto).

• ReadableStream, WritableStream, TransformStream — mediante el módulo integrado node:stream/web.

• structuredClone, MessageChannel/MessagePort — por si acaso, mediante node:v8 y node:worker_threads.

Todo esto está al principio de server.mjs, antes de importar Express y el SDK de MCP (se hace con await import(...), no con un import normal al inicio del archivo; ver el siguiente punto para saber por qué).

6.2. El dominio no estaba «vinculado» a la carpeta del sitio

Después de subir el código al servidor, el sitio mostraba la página característica de Beget «El dominio no está vinculado al directorio del servidor» en lugar de la aplicación. No basta con crear la carpeta del sitio y subir los archivos: el dominio hay que «vincularlo» por separado a través del panel: Sitios → sitio correspondiente → ⋮ → «Vincular dominio». Un paso poco evidente que es fácil pasar por alto.

6.3. ERR_REQUIRE_ESM: Passenger no puede cargar módulos ES

Passenger en Beget (versión antigua, passenger40) inicia el archivo de arranque mediante require(), y require() en Node no puede cargar módulos ES por diseño (import/export, type: module en package.json). server.mjs usa await en el nivel superior del archivo, lo cual solo es posible en un módulo ES.

Solución: en package.json no hay "type": "module" (por defecto, .js es CommonJS); el código está en un archivo con extensión .mjs (la extensión .mjs siempre es un módulo ES, independientemente de package.json), y el punto de entrada para Passenger es app.js, un archivo CommonJS muy pequeño:

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

require() carga app.js sin problemas (es CommonJS normal), y dentro de él un import() dinámico (es una función, no una declaración) ya puede cargar de forma asíncrona el módulo ES server.mjs.

6.4. El secreto en la ruta de la URL

MCP_PATH_SECRET es una cadena aleatoria (por ejemplo, secrets.token_urlsafe(32) en Python, o crypto.randomUUID() + crypto.randomUUID() en la consola del navegador). Si hace falta renovar el secreto, se genera uno nuevo y se actualiza en el .htaccess del servidor y en los ajustes del conector en Claude.

7. Cómo conectarlo en Claude

1. claude.ai → Configuración → Connectors → Add custom connector.

2. Name: Bitrix24 (cualquiera).

3. Remote MCP server URL: https://mcp-bitrix.karpovpartners-it.ru/mcp/<секрет>

4. OAuth Client ID / Secret — dejar vacíos, no son necesarios (la autorización ya está incrustada en la URL).

5. Guardar y activar el conector en el chat.

8. Pregunta abierta — el conector MCP nativo de Bitrix24

Vale la pena escribir al soporte de Bitrix24 sobre el conector MCP nativo roto («B24» en el marketplace): /authorize y los endpoints estándar de descubrimiento OAuth devuelven un nginx 404 puro con los ajustes activados y la suscripción activa. Cuando/si Bitrix24 lo arregle, se podrá cambiar al conector oficial, o dejar este puente: también es funcional y ofrece más control (por ejemplo, limitar los métodos a CRM+Tareas directamente en el código).