Bitrix24

Interactúa con y gestiona tu instancia de CRM de Bitrix24 a través de un potente conjunto de herramientas.

GitHub
33
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Bitrix24

Un servidor integral del Protocolo de Contexto de Modelos (MCP) para la integración con Bitrix24 CRM, que permite a los agentes de IA interactuar sin problemas con su instancia de Bitrix24 a través de un potente conjunto de herramientas.

🚀 Características

  • Gestión completa de CRM: Crear, leer, actualizar y listar contactos, negocios y tareas
  • Búsqueda avanzada: Busque en todas las entidades de CRM con filtrado flexible
  • Límite de velocidad: Límite de velocidad integrado para respetar los límites de la API de Bitrix24
  • Seguridad de tipos: Implementación completa en TypeScript con definiciones de tipos exhaustivas
  • Manejo de errores: Manejo y validación de errores robustos
  • Integración sencilla: Configuración simple con Claude Desktop y otros clientes compatibles con MCP

📋 Herramientas disponibles

Gestión de contactos

  • bitrix24_create_contact - Crear nuevos contactos
  • bitrix24_get_contact - Recuperar contacto por ID
  • bitrix24_list_contacts - Listar contactos con filtrado
  • bitrix24_update_contact - Actualizar contactos existentes

Gestión de negocios

  • bitrix24_create_deal - Crear nuevos negocios
  • bitrix24_get_deal - Recuperar negocio por ID
  • bitrix24_list_deals - Listar negocios con filtrado
  • bitrix24_update_deal - Actualizar negocios existentes

Gestión de tareas

  • bitrix24_create_task - Crear nuevas tareas
  • bitrix24_get_task - Recuperar tarea por ID
  • bitrix24_list_tasks - Listar tareas con filtrado
  • bitrix24_update_task - Actualizar tareas existentes

Gestión de usuarios

  • bitrix24_get_user - Obtener información del usuario por ID
  • bitrix24_get_all_users - Obtener todos los usuarios del sistema con nombres y detalles
  • bitrix24_resolve_user_names - Resolver IDs de usuario a nombres de usuario
  • bitrix24_get_contacts_with_user_names - Obtener contactos con nombres de usuario resueltos
  • bitrix24_get_deals_with_user_names - Obtener negocios con nombres de usuario resueltos
  • bitrix24_get_leads_with_user_names - Obtener prospectos con nombres de usuario resueltos
  • bitrix24_get_companies_with_user_names - Obtener empresas con nombres de usuario resueltos

Gestión de prospectos

  • bitrix24_create_lead - Crear nuevos prospectos
  • bitrix24_get_lead - Recuperar prospecto por ID
  • bitrix24_list_leads - Listar prospectos con filtrado
  • bitrix24_get_latest_leads - Obtener los prospectos más recientes
  • bitrix24_get_leads_from_date_range - Obtener prospectos de un rango de fechas específico
  • bitrix24_update_lead - Actualizar prospectos existentes

Gestión de empresas

  • bitrix24_create_company - Crear nuevas empresas
  • bitrix24_get_company - Recuperar empresa por ID
  • bitrix24_list_companies - Listar empresas con filtrado
  • bitrix24_get_latest_companies - Obtener las empresas más recientes
  • bitrix24_get_companies_from_date_range - Obtener empresas de un rango de fechas específico
  • bitrix24_update_company - Actualizar empresas existentes

Filtrado mejorado de negocios

  • bitrix24_get_deal_pipelines - Obtener todos los pipelines/categorías de negocios
  • bitrix24_get_deal_stages - Obtener etapas de negocios para pipelines
  • bitrix24_filter_deals_by_pipeline - Filtrar negocios por pipeline
  • bitrix24_filter_deals_by_budget - Filtrar negocios por rango de presupuesto
  • bitrix24_filter_deals_by_status - Filtrar negocios por etapa/estado

Utilidades

  • bitrix24_search_crm - Buscar en entidades de CRM
  • bitrix24_get_current_user - Obtener información del usuario actual
  • bitrix24_validate_webhook - Validar conexión de webhook
  • bitrix24_diagnose_permissions - Diagnosticar permisos de webhook
  • bitrix24_check_crm_settings - Verificar configuración y ajustes de CRM
  • bitrix24_test_leads_api - Probar endpoints de la API de prospectos

Monitoreo del equipo de ventas

  • bitrix24_monitor_user_activities - Monitorear actividades de usuarios (llamadas, correos, interacciones en la línea de tiempo, tiempos de respuesta)
  • bitrix24_get_user_performance_summary - Obtener resumen integral de rendimiento con métricas de negocios y tasas de conversión
  • bitrix24_analyze_account_performance - Analizar rendimiento de cuentas específicas (empresas/contactos)
  • bitrix24_compare_user_performance - Comparar métricas de rendimiento entre múltiples usuarios
  • bitrix24_track_deal_progression - Rastrear progresión de negocios a través de etapas de pipeline con análisis de tiempos
  • bitrix24_monitor_sales_activities - Monitorear actividades relacionadas con ventas (tareas, seguimientos, reuniones)
  • bitrix24_generate_sales_report - Generar informes de ventas integrales con métricas personalizables
  • bitrix24_get_team_dashboard - Obtener panel de rendimiento del equipo en tiempo real
  • bitrix24_analyze_customer_engagement - Analizar patrones de participación del cliente y salud de las relaciones
  • bitrix24_forecast_performance - Generar pronósticos de rendimiento y análisis predictivos

🛠️ Instalación

Requisitos previos

  • Node.js 18+
  • npm o yarn
  • URL de webhook de Bitrix24

Configuración

  1. Clonar e instalar dependencias:
git clone <repository-url>
cd bitrix24-mcp-server
npm install
  1. Configurar el entorno:
cp .env.example .env
# Edit .env with your Bitrix24 webhook URL
  1. Compilar el proyecto:
npm run build
  1. Probar la conexión:
npm test

⚙️ Configuración

Variables de entorno

Cree un archivo .env con las siguientes variables:

BITRIX24_WEBHOOK_URL=https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/
NODE_ENV=development
LOG_LEVEL=info

Configuración del webhook de Bitrix24

  1. Vaya a su instancia de Bitrix24
  2. Navegue a Aplicaciones → Webhooks
  3. Cree un webhook entrante
  4. Copie la URL del webhook (formato: https://domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/)
  5. Establezca los permisos apropiados para CRM y Tareas

🔧 Integración con Claude Desktop

Agregue lo siguiente a su archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/path/to/your/bitrix24-mcp-server/build/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"
      }
    }
  }
}

📖 Ejemplos de uso

Crear un contacto

Create a new contact named John Smith with email john@example.com and phone +39 123 456 789

Crear un negocio con contacto

Create a new contact for Maria Rossi with email maria@company.com, then create a deal titled "Website Development Project" for €5000 and link it to this contact

Gestionar tareas

Create a task titled "Follow up with client" with high priority, deadline tomorrow, and link it to contact ID 123

Buscar en CRM

Search for all contacts and deals related to "example.com"

🏗️ Desarrollo

Estructura del proyecto

bitrix24-mcp-server/
├── src/
│   ├── bitrix24/
│   │   └── client.ts          # Bitrix24 API client
│   ├── tools/
│   │   └── index.ts           # MCP tools definitions
│   ├── utils/
│   │   └── logger.ts          # Logging utilities
│   ├── config/
│   │   └── index.ts           # Configuration management
│   └── index.ts               # Main MCP server
├── test/
│   └── integration.test.js    # Integration tests
├── build/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Comandos de desarrollo

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Run tests
npm test

# Start the server
npm start

Agregar nuevas herramientas

  1. Defina la herramienta en src/tools/index.ts:
export const newTool: Tool = {
  name: 'bitrix24_new_action',
  description: 'Description of the new action',
  inputSchema: {
    type: 'object',
    properties: {
      // Define parameters
    },
    required: ['requiredParam']
  }
};
  1. Agregue el manejador de ejecución:
case 'bitrix24_new_action':
  // Implementation
  return { success: true, result: 'Action completed' };
  1. Agregue al arreglo allTools y recompile.

🔒 Consideraciones de seguridad

  • Seguridad del webhook: Mantenga su URL de webhook en secreto y rótela regularmente
  • Variables de entorno: Nunca envíe archivos .env al control de versiones
  • Límite de velocidad: El cliente incluye límite de velocidad integrado (2 solicitudes/segundo)
  • Manejo de errores: La información sensible no se expone en los mensajes de error

🐛 Solución de problemas

Problemas comunes

"Falló la validación del webhook"

  • Verifique que su URL de webhook sea correcta
  • Compruebe que el webhook tenga los permisos apropiados
  • Asegúrese de que su instancia de Bitrix24 sea accesible

Errores de "No se puede encontrar el módulo"

  • Ejecute npm install para instalar dependencias
  • Asegúrese de haber compilado el proyecto con npm run build

Errores de límite de velocidad

  • El cliente maneja automáticamente el límite de velocidad
  • Si ve errores persistentes de límite de velocidad, considere reducir la frecuencia de solicitudes

Modo de depuración

Establezca NODE_ENV=development y LOG_LEVEL=debug en su archivo .env para obtener registros detallados.

📝 Referencia de API

Métodos de Bitrix24Client

Contactos

  • createContact(contact: BitrixContact): Promise<string>
  • getContact(id: string): Promise<BitrixContact>
  • updateContact(id: string, contact: Partial<BitrixContact>): Promise<boolean>
  • listContacts(params?: ListParams): Promise<BitrixContact[]>

Negocios

  • createDeal(deal: BitrixDeal): Promise<string>
  • getDeal(id: string): Promise<BitrixDeal>
  • updateDeal(id: string, deal: Partial<BitrixDeal>): Promise<boolean>
  • listDeals(params?: ListParams): Promise<BitrixDeal[]>

Tareas

  • createTask(task: BitrixTask): Promise<string>
  • getTask(id: string): Promise<BitrixTask>
  • updateTask(id: string, task: Partial<BitrixTask>): Promise<boolean>
  • listTasks(params?: TaskListParams): Promise<BitrixTask[]>

Usuarios

  • getUser(userId: string): Promise<any>
  • getAllUsers(): Promise<any[]>
  • getUsersByIds(userIds: string[]): Promise<any[]>
  • resolveUserNames(userIds: string[]): Promise<Record<string, string>>
  • enhanceWithUserNames<T>(items: T[], userIdFields?: string[]): Promise<T[]>

Utilidades

  • getCurrentUser(): Promise<any>
  • searchCRM(query: string, entityTypes?: string[]): Promise<any>
  • validateWebhook(): Promise<boolean>

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Agregue pruebas si corresponde
  5. Envíe una solicitud de extracción

📄 Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles.

🆘 Soporte

Para problemas y preguntas:

  1. Consulte la sección de solución de problemas
  2. Revise la documentación de la API de Bitrix24
  3. Abra un problema en GitHub

Creado con ❤️ para la comunidad de automatización con IA