mcp-b24

🇷🇺 Русский · 🇬🇧 English

Servidor MCP completo sobre la API REST de Bitrix24 — supera al limitado mcp-bitrix24 (solo Tasks) y al MCP oficial de Bitrix24 (solo la referencia de documentación). Realmente ejecuta llamadas REST al portal: CRM, tareas, chats, archivos, calendario, RR. HH., procesos inteligentes, correo, telefonía, procesos de negocio, eventos.

• 30 herramientas (28 de dominio + bx24_batch + bx24_call), ~290 acciones.

• Autenticación: webhook entrante u OAuth 2.0 con renovación automática del token (client_endpoint).

• Transporte: stdio (Claude Desktop, Cursor, Codex) y Streamable HTTP.

• Seguridad: confirmación en dos fases de las acciones destructivas, auditoría JSONL, límite de velocidad token-bucket, backoff para QUERY_LIMIT_EXCEEDED/OPERATION_TIME_LIMIT.

• Localización RU/EN (BX24_DEFAULT_LANG). 73 pruebas, TypeScript ESM, MIT.

Insignias: npm v0.2.0 · MIT · Node.js ≥ 18 · MCP 1.x · Bitrix24 REST 1.0 + 3.0.

Documentación

Related MCP server: fast-bitrix24-mcp

Inicio rápido

npm install -g mcp-b24
# или без установки:
npx -y mcp-b24

Autenticación (a elegir)

Webhook (más sencillo):

export BX24_WEBHOOK_URL="https://ВАШ_ПОРТАЛ.bitrix24.ru/rest/1/КОД_ВЕБХУКА/"

Aplicación OAuth (escala del portal, renovación automática):

export BX24_MODE=oauth
export BX24_DOMAIN=ВАШ_ПОРТАЛ.bitrix24.ru
export BX24_CLIENT_ID="..."
export BX24_CLIENT_SECRET="..."
export BX24_REFRESH_TOKEN="..."

Todas las variables están en .env.example.

Configuración de clientes MCP

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "bitrix24": {
      "command": "npx",
      "args": ["-y", "mcp-b24"],
      "env": {
        "BX24_WEBHOOK_URL": "https://ВАШ_ПОРТАЛ.bitrix24.ru/rest/1/КОД_ВЕБХУКА/",
        "BX24_CONFIRM_DESTRUCTIVE": "true"
      }
    }
  }
}

Windows (cmd): "command": "cmd", "args": ["/c", "npx", "-y", "mcp-b24"].

Cursor (.cursor/mcp.json) — el mismo bloque mcpServers. VS Code (.vscode/mcp.json) — la clave servers en lugar de mcpServers. Codex CLI: codex mcp add bitrix24 --env BX24_WEBHOOK_URL=... -- npx -y mcp-b24. Cline / Roo Code — bloque mcpServers igual que para Claude Desktop.

Streamable HTTP:

BX24_TRANSPORT=http BX24_HTTP_PORT=3000 BX24_WEBHOOK_URL="..." npx mcp-b24
# http://127.0.0.1:3000/mcp

Docker:

docker build -t mcp-b24 .
docker run --rm -e BX24_WEBHOOK_URL="..." mcp-b24          # stdio
docker compose up                                                   # HTTP (см. docker-compose.yml)

Herramientas (28 de dominio + 2 genéricas)

CRM: bx24_crm_leads, bx24_crm_deals, bx24_crm_contacts, bx24_crm_companies, bx24_crm_invoices, bx24_crm_products, bx24_crm_activities, bx24_crm_requisites, bx24_crm_duplicates, bx24_smart_processes. collab: bx24_tasks, bx24_projects, bx24_disk, bx24_im, bx24_im_chat, bx24_conf, bx24_calendar. org: bx24_users, bx24_departments, bx24_time, bx24_hr. biz: bx24_lists, bx24_mail, bx24_reports, bx24_marketing, bx24_workflows, bx24_telephony, bx24_events. generic: bx24_batch (≤50 llamadas), bx24_call (cualquier método REST por nombre).

Cada herramienta de dominio es basada en acciones: la operación se elige mediante el parámetro action. El registro completo de acciones está en docs/TOOLS_REFERENCE.md.

Ejemplos de solicitudes

• ¿«Crea un lead de Iván, teléfono +7…» → bx24_crm_leads action=add

• «Muéstrame mis tareas de hoy» → bx24_tasks action=list

• «Sube el PDF a "Contratos 2026" y envía el enlace al chat "Partners"» → bx24_disk + bx24_im_chat

• «Inicia el proceso de negocio de aprobación de la transacción #456» → bx24_workflows action=start

• «Elimina la compañía "Vieja empresa"» → bx24_crm_companies action=delete (pedirá confirmación)

Desarrollo

npm install
npm run build        # tsc → dist/
npm test             # 73 теста
npm run test:coverage
npm start            # node dist/index.js

Más información: docs/DEVELOPER_GUIDE.md.

Licencia

MIT © Penzin Konstantin (github.com/kostikpenzin)