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:///rest/<user_id>//"

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.