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

Example Codex MCP config:

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

[mcp_servers.bitrix24.env]
BITRIX24_WEBHOOK_URL = "https:///rest///"

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.