mcp-bitrix24

mcp-bitrix24

Servidor MCP para Tarefas, Grupos de Trabalho e Usuários do Bitrix24. Implementa MCP/JSON-RPC sobre STDIO.

Recursos

• Tarefas: criar, atualizar, fechar, reabrir, listar
• Grupos de trabalho: criar, listar
• Usuários: listar, usuário atual, campos disponíveis
• Campos de tarefa: campos disponíveis + validação para create_task.fields

Requisitos

• Node.js >= 18
• URL do webhook do Bitrix24

Instalação / Compilação

npm install
npm run build

Execute via npm:

npx mcp-bitrix24

Configuração

Defina a URL do webhook do Bitrix24 via variável de ambiente:

BITRIX24_WEBHOOK_URL=https://<your-domain>/rest/<user_id>/<webhook>/

Exemplo de configuração MCP do Codex:

[mcp_servers.bitrix24]
command = "npx"
args = ["-y", "mcp-bitrix24"]

[mcp_servers.bitrix24.env]
BITRIX24_WEBHOOK_URL = "https://<your-domain>/rest/<user_id>/<webhook>/"

Ferramentas

Tarefas

• create_task
  • Entrada: title (string, obrigatório), description? (string), responsible_id? (number), group_id? (number), fields? (object)
    • Saída: { task_id: number }
    • Nota: se fields for fornecido, as chaves são validadas contra get_task_fields.
• update_task
  • Entrada: task_id (number, obrigatório) + pelo menos um de: title?, description?, responsible_id?, group_id?
    • Saída: { task_id: number }
• close_task
  • Entrada: task_id (number, obrigatório)
    • Saída: { task_id: number }
• reopen_task
  • Entrada: task_id (number, obrigatório)
    • Saída: { task_id: number }
• list_tasks
  • Entrada: responsible_id? (number), group_id? (number), start? (number), limit? (number)
    • Saída: { tasks: [{ id, title, status }] }
• get_task_fields
  • Entrada: {}
    • Saída: { fields: { [field: string]: object } }
• list_task_history
  • Entrada: task_id (number, obrigatório), filter? (object), order? (object)
    • Saída: { list: [ { id, createdDate, field, value, user } ] }

Grupos de Trabalho

• create_group
  • Entrada: name (string, obrigatório), description? (string)
    • Saída: { group_id: number }
• list_groups
  • Entrada: limit? (number)
    • Saída: { groups: [{ id, name }] }

Usuários

• list_users
  • Entrada:
    • filter? (object) - sort? (string) - order? ("ASC" | "DESC") - admin_mode? (boolean) - start? (number) - limit? (number)
    • Saída: { users: [{ id, name, last_name, email?, active }] }
    • Nota: filter suporta filtros user.get do Bitrix24 (incluindo prefixos como >=, %, @, etc.). start controla a paginação (o Bitrix retorna 50 registros por página); limit é um recorte local após a resposta da API.
• get_user_fields
  • Entrada: {}
    • Saída: { fields: { [field: string]: string } }
• get_current_user
  • Entrada: {}
    • Saída: { user: { id, name, last_name, email?, active } }

Arquitetura

Camadas de arquitetura limpa:

• mcp/ — protocolo, transporte, servidor
• adapters/ — mapeamento das ferramentas MCP para o domínio
• domain/ — entidades, serviços, portas
• infrastructure/ — cliente REST do Bitrix24

Notas de Desenvolvimento

• A validação de entrada usa zod.
• Transporte: apenas STDIO.
• Compilação: tsc (npm run build).

Contribuindo

Veja CONTRIBUTING.md para diretrizes.