# 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://<your-domain>/rest/<user_id>/<webhook>/ ``` Example Codex MCP config: ```toml [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.