mcp-bitrix24

MCP server for Bitrix24 Tasks, Workgroups, and Users. Implements MCP/JSON-RPC over STDIO.

Features

• Tasks: create, update, close, reopen, list
• Workgroups: create, list
• Users: list, current user, available fields
• Task fields: available fields + validation for create_task.fields

Requirements

• Node.js >= 18
• Bitrix24 webhook URL

Install / Build

npm install
npm run build

Run via npm:

npx mcp-bitrix24

Configuration

Set the Bitrix24 webhook URL via environment variable:

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

Example Codex MCP config:

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

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

Tools

Tasks

• create_task

  • Input: title (string, required), description? (string), responsible_id? (number), group_id? (number), fields? (object)
  • Output: { task_id: number }
  • Note: if fields is provided, keys are validated against get_task_fields.

• update_task

  • Input: task_id (number, required) + at least one of: title?, description?, responsible_id?, group_id?
  • Output: { task_id: number }

• close_task

  • Input: task_id (number, required)
  • Output: { task_id: number }

• reopen_task

  • Input: task_id (number, required)
  • Output: { task_id: number }

• list_tasks

  • Input: responsible_id? (number), group_id? (number), start? (number), limit? (number)
  • Output: { tasks: [{ id, title, status }] }

• get_task_fields

  • Input: {}
  • Output: { fields: { [field: string]: object } }

• list_task_history

  • Input: task_id (number, required), filter? (object), order? (object)
  • Output: { list: [ { id, createdDate, field, value, user } ] }

Workgroups

• create_group

  • Input: name (string, required), description? (string)
  • Output: { group_id: number }

• list_groups

  • Input: limit? (number)
  • Output: { groups: [{ id, name }] }

Users

• list_users

  • Input:
    • filter? (object)
    • sort? (string)
    • order? ("ASC" | "DESC")
    • admin_mode? (boolean)
    • start? (number)
    • limit? (number)
  • Output: { users: [{ id, name, last_name, email?, active }] }
  • Note: filter supports Bitrix24 user.get filters (including prefixes like >=, %, @, etc.). start controls paging (Bitrix returns 50 records per page); limit is a local slice after the API response.

• get_user_fields

  • Input: {}
  • Output: { fields: { [field: string]: string } }

• get_current_user

  • Input: {}
  • Output: { user: { id, name, last_name, email?, active } }

Architecture

Clean architecture layers:

• mcp/ — protocol, transport, server
• adapters/ — MCP tools mapping to domain
• domain/ — entities, services, ports
• infrastructure/ — Bitrix24 REST client

Development Notes

• Input validation uses zod.
• Transport: STDIO only.
• Build: tsc (npm run build).

Contributing

See CONTRIBUTING.md for guidelines.