bitrix24-mcp-server

# Bitrix24 MCP Server > Conecta tu portal Bitrix24 con Claude AI via Model Context Protocol (MCP) > by **[Bit24 SL](https://bit24.es)** — Especialistas en Bitrix24 para asesorías --- ## ¿Qué es esto? Un servidor MCP que expone las principales funcionalidades de **Bitrix24 CRM** directamente en Claude (Desktop, Claude.ai con conectores, o cualquier cliente MCP compatible). Con este conector, Claude puede: - 🔍 **Consultar** contactos, deals, tareas, empresas y actividades - ✏️ **Crear y actualizar** registros CRM directamente desde la conversación - 📊 **Analizar** el pipeline y generar reportes en lenguaje natural - 🔄 **Mover deals** entre etapas del embudo - 🤖 **Automatizar** flujos de trabajo CRM con IA --- ## Herramientas disponibles (22 tools) | Módulo | Herramientas | |--------|-------------| | **Contactos** | `b24_get_contact`, `b24_list_contacts`, `b24_create_contact`, `b24_update_contact` | | **Deals** | `b24_get_deal`, `b24_list_deals`, `b24_create_deal`, `b24_move_deal_stage` | | **Pipeline** | `b24_list_pipelines`, `b24_list_stages` | | **Tareas** | `b24_get_task`, `b24_list_tasks`, `b24_create_task`, `b24_update_task` | | **Actividades** | `b24_list_activities`, `b24_create_activity` | | **Empresas** | `b24_get_company`, `b24_list_companies` | | **Usuarios** | `b24_list_users`, `b24_get_current_user` | | **SPA** | `b24_list_spa_types`, `b24_list_spa_items` | | **Analytics** | `b24_crm_stats` | --- ## Instalación rápida ### Requisitos - Node.js >= 18 - Bitrix24 con acceso a webhooks - Claude Desktop (o cualquier cliente MCP) ### 1. Clonar e instalar ```bash git clone https://github.com/tu-usuario/bitrix24-mcp-server.git cd bitrix24-mcp-server npm install npm run build ``` ### 2. Configurar el webhook de Bitrix24 1. En tu portal Bitrix24: **Configuración** → **Desarrollador** → **Webhooks entrantes** 2. Crear nuevo webhook con permisos: `CRM`, `Tareas`, `Usuarios` 3. Copiar la URL generada ```bash cp .env.example .env # Editar .env con tu webhook URL ``` ```env BITRIX24_WEBHOOK_URL=https://tuportal.bitrix24.es/rest/1/tu_token/ ``` ### 3. Configurar Claude Desktop Editar `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "bitrix24": { "command": "node", "args": ["/ruta/absoluta/a/bitrix24-mcp-server/dist/index.js"], "env": { "BITRIX24_WEBHOOK_URL": "https://tuportal.bitrix24.es/rest/1/tu_token/" } } } } ``` > **Alternativa con npx** (si publicas en npm): > ```json > { > "mcpServers": { > "bitrix24": { > "command": "npx", > "args": ["bitrix24-mcp-server"], > "env": { "BITRIX24_WEBHOOK_URL": "https://..." } > } > } > } > ``` ### 4. Reiniciar Claude Desktop Cierra y vuelve a abrir Claude Desktop. Verás el icono 🔌 indicando que el conector está activo. --- ## Ejemplos de uso con Claude Una vez conectado, puedes hacer preguntas como: ``` "¿Cuántos deals tengo abiertos en el pipeline de Renta?" "Crea un contacto llamado María García de la empresa Asesoría Perez SL, con origen 'Congreso Valencia' y sector 'FISCAL'" "Lista los 10 deals más recientes con su etapa y responsable" "Mueve el deal #1234 a la etapa 'Propuesta enviada'" "¿Cuántas tareas pendientes tiene el usuario con ID 5?" "Registra una llamada realizada hoy con el contacto #567 sobre la campaña de la renta" ``` --- ## Permisos del Webhook El webhook necesita los siguientes scopes en Bitrix24: | Scope | Para qué | |-------|----------| | `crm` | Contactos, deals, empresas, actividades | | `task` | Tareas | | `user` | Información de usuarios | | `bizproc` | (Opcional) Procesos de negocio | --- ## Campos CRM recomendados para asesorías Siguiendo la metodología **Bit24** de los 3 campos obligatorios para segmentación AI: | Campo Bitrix24 | Propósito | |----------------|-----------| | `SOURCE_ID` / `UF_CRM_ORIGEN` | Origen del contacto | | `UF_CRM_TIPO_CLIENTE` | Tipo de cliente (persona física, empresa...) | | `UF_CRM_SECTOR` | Sector de actividad (FISCAL, LABORAL, CONTABLE...) | --- ## Desarrollo ```bash # Modo desarrollo con hot-reload npm run dev # Compilar TypeScript npm run build # Ejecutar directamente npm start ``` ### Estructura del proyecto ``` bitrix24-mcp-server/ ├── src/ │ ├── index.ts # Servidor MCP principal │ ├── bitrix24-client.ts # Cliente HTTP para la API REST de Bitrix24 │ ├── tools.ts # Definición de herramientas MCP │ └── handlers.ts # Lógica de cada herramienta ├── dist/ # Compilado (generado por npm run build) ├── .env.example ├── package.json └── tsconfig.json ``` --- ## Añadir nuevas herramientas 1. Añadir el método en `bitrix24-client.ts` 2. Definir el schema en `tools.ts` 3. Implementar el handler en `handlers.ts` --- ## Licencia MIT — Bit24 SL --- ## Soporte - 🌐 [bit24.es](https://bit24.es) - 📧 info@bit24.es - 💬 [comunidadbit24.com](https://comunidadbit24.com)