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