Bitrix24

Interaja e gerencie sua instância do CRM Bitrix24 através de um conjunto poderoso de ferramentas.

GitHub
33
Experimente este MCPPatrocinado

Documentação

Servidor MCP Bitrix24

Um servidor abrangente do Model Context Protocol (MCP) para integração com o CRM Bitrix24, permitindo que agentes de IA interajam perfeitamente com sua instância Bitrix24 por meio de um poderoso conjunto de ferramentas.

🚀 Recursos

  • Gerenciamento completo de CRM: Crie, leia, atualize e liste contatos, negócios e tarefas
  • Busca avançada: Pesquise em todas as entidades do CRM com filtros flexíveis
  • Limitação de taxa: Limitação de taxa integrada para respeitar os limites da API do Bitrix24
  • Segurança de tipos: Implementação completa em TypeScript com definições de tipos abrangentes
  • Tratamento de erros: Tratamento robusto de erros e validação
  • Integração fácil: Configuração simples com Claude Desktop e outros clientes compatíveis com MCP

📋 Ferramentas Disponíveis

Gerenciamento de Contatos

  • bitrix24_create_contact - Criar novos contatos
  • bitrix24_get_contact - Recuperar contato por ID
  • bitrix24_list_contacts - Listar contatos com filtros
  • bitrix24_update_contact - Atualizar contatos existentes

Gerenciamento de Negócios

  • bitrix24_create_deal - Criar novos negócios
  • bitrix24_get_deal - Recuperar negócio por ID
  • bitrix24_list_deals - Listar negócios com filtros
  • bitrix24_update_deal - Atualizar negócios existentes

Gerenciamento de Tarefas

  • bitrix24_create_task - Criar novas tarefas
  • bitrix24_get_task - Recuperar tarefa por ID
  • bitrix24_list_tasks - Listar tarefas com filtros
  • bitrix24_update_task - Atualizar tarefas existentes

Gerenciamento de Usuários

  • bitrix24_get_user - Obter informações do usuário por ID
  • bitrix24_get_all_users - Obter todos os usuários do sistema com nomes e detalhes
  • bitrix24_resolve_user_names - Resolver IDs de usuários para nomes de usuários
  • bitrix24_get_contacts_with_user_names - Obter contatos com nomes de usuários resolvidos
  • bitrix24_get_deals_with_user_names - Obter negócios com nomes de usuários resolvidos
  • bitrix24_get_leads_with_user_names - Obter leads com nomes de usuários resolvidos
  • bitrix24_get_companies_with_user_names - Obter empresas com nomes de usuários resolvidos

Gerenciamento de Leads

  • bitrix24_create_lead - Criar novos leads
  • bitrix24_get_lead - Recuperar lead por ID
  • bitrix24_list_leads - Listar leads com filtros
  • bitrix24_get_latest_leads - Obter leads mais recentes
  • bitrix24_get_leads_from_date_range - Obter leads de um intervalo de datas específico
  • bitrix24_update_lead - Atualizar leads existentes

Gerenciamento de Empresas

  • bitrix24_create_company - Criar novas empresas
  • bitrix24_get_company - Recuperar empresa por ID
  • bitrix24_list_companies - Listar empresas com filtros
  • bitrix24_get_latest_companies - Obter empresas mais recentes
  • bitrix24_get_companies_from_date_range - Obter empresas de um intervalo de datas específico
  • bitrix24_update_company - Atualizar empresas existentes

Filtragem Avançada de Negócios

  • bitrix24_get_deal_pipelines - Obter todos os pipelines/categorias de negócios
  • bitrix24_get_deal_stages - Obter estágios de negócios para pipelines
  • bitrix24_filter_deals_by_pipeline - Filtrar negócios por pipeline
  • bitrix24_filter_deals_by_budget - Filtrar negócios por faixa de orçamento
  • bitrix24_filter_deals_by_status - Filtrar negócios por estágio/status

Utilitários

  • bitrix24_search_crm - Pesquisar em entidades do CRM
  • bitrix24_get_current_user - Obter informações do usuário atual
  • bitrix24_validate_webhook - Validar conexão do webhook
  • bitrix24_diagnose_permissions - Diagnosticar permissões do webhook
  • bitrix24_check_crm_settings - Verificar configurações e definições do CRM
  • bitrix24_test_leads_api - Testar endpoints da API de leads

Monitoramento da Equipe de Vendas

  • bitrix24_monitor_user_activities - Monitorar atividades dos usuários (chamadas, e-mails, interações na linha do tempo, tempos de resposta)
  • bitrix24_get_user_performance_summary - Obter resumo abrangente de desempenho com métricas de negócios e taxas de conversão
  • bitrix24_analyze_account_performance - Analisar desempenho de contas específicas (empresas/contatos)
  • bitrix24_compare_user_performance - Comparar métricas de desempenho entre vários usuários
  • bitrix24_track_deal_progression - Acompanhar a progressão de negócios pelos estágios do pipeline com análise de tempo
  • bitrix24_monitor_sales_activities - Monitorar atividades relacionadas a vendas (tarefas, acompanhamentos, reuniões)
  • bitrix24_generate_sales_report - Gerar relatórios de vendas abrangentes com métricas personalizáveis
  • bitrix24_get_team_dashboard - Obter painel de desempenho da equipe em tempo real
  • bitrix24_analyze_customer_engagement - Analisar padrões de engajamento do cliente e saúde do relacionamento
  • bitrix24_forecast_performance - Gerar previsões de desempenho e análises preditivas

🛠️ Instalação

Pré-requisitos

  • Node.js 18+
  • npm ou yarn
  • URL do webhook do Bitrix24

Configuração

  1. Clone e instale as dependências:
git clone <repository-url>
cd bitrix24-mcp-server
npm install
  1. Configure o ambiente:
cp .env.example .env
# Edit .env with your Bitrix24 webhook URL
  1. Compile o projeto:
npm run build
  1. Teste a conexão:
npm test

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env com as seguintes variáveis:

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

Configuração do Webhook do Bitrix24

  1. Acesse sua instância do Bitrix24
  2. Navegue até Aplicativos → Webhooks
  3. Crie um webhook de entrada
  4. Copie a URL do webhook (formato: https://domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/)
  5. Defina as permissões apropriadas para CRM e Tarefas

🔧 Integração com Claude Desktop

Adicione o seguinte ao arquivo de configuração do 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/"
      }
    }
  }
}

📖 Exemplos de Uso

Criando um Contato

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

Criando um Negócio com Contato

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

Gerenciando Tarefas

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

Pesquisando no CRM

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

🏗️ Desenvolvimento

Estrutura do Projeto

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 Desenvolvimento

# 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

Adicionando Novas Ferramentas

  1. Defina a ferramenta em 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. Adicione o manipulador de execução:
case 'bitrix24_new_action':
  // Implementation
  return { success: true, result: 'Action completed' };
  1. Adicione ao array allTools e recompile.

🔒 Considerações de Segurança

  • Segurança do Webhook: Mantenha sua URL de webhook em segredo e rotacione-a regularmente
  • Variáveis de Ambiente: Nunca envie arquivos .env para o controle de versão
  • Limitação de Taxa: O cliente inclui limitação de taxa integrada (2 solicitações/segundo)
  • Tratamento de Erros: Informações sensíveis não são expostas em mensagens de erro

🐛 Solução de Problemas

Problemas Comuns

"Falha na validação do webhook"

  • Verifique se a URL do webhook está correta
  • Confirme que o webhook tem as permissões adequadas
  • Garanta que sua instância do Bitrix24 esteja acessível

Erros de "módulo não encontrado"

  • Execute npm install para instalar as dependências
  • Certifique-se de ter compilado o projeto com npm run build

Erros de limitação de taxa

  • O cliente lida automaticamente com a limitação de taxa
  • Se você vir erros persistentes de limite de taxa, considere reduzir a frequência das solicitações

Modo de Depuração

Defina NODE_ENV=development e LOG_LEVEL=debug no seu arquivo .env para obter registros detalhados.

📝 Referência da API

Métodos do Bitrix24Client

Contatos

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

Negócios

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

Tarefas

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

Usuários

  • 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[]>

Utilitários

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

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes, se aplicável
  5. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🆘 Suporte

Para problemas e perguntas:

  1. Consulte a seção de solução de problemas
  2. Revise a documentação da API do Bitrix24
  3. Abra uma issue no GitHub

Feito com ❤️ para a comunidade de automação com IA