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

``bash
npm install
npm run build
`

Run via npm:

`bash
npx mcp-bitrix24
`

Configuration

Set the Bitrix24 webhook URL via environment variable:

`
BITRIX24_WEBHOOK_URL=https:///rest///
`

Example Codex MCP config:

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

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

Tools

$3

- 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 } ] }

$3

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

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

$3

- 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.