Bitrix24 Tasks and CRM MCP Server

MCP server for Bitrix24 focused on:

• tasks (tasks.task.*)
• projects/workgroups (sonet_group.*)
• users (user.*)
• CRM leads, companies, contacts, and requisites (crm.*)

Quick start (without npm install)

Use npx in your MCP client config. This installs and runs the package automatically.

{
  "mcpServers": {
    "bitrix24": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"
      }
    }
  }
}

If you want latest version each run:

{
  "mcpServers": {
    "bitrix24": {
      "command": "npx",
      "args": ["-y", "bitrix24-tasks-mcp-server"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"
      }
    }
  }
}

Alternative installation

Global:

npm install -g bitrix24-tasks-mcp-server

Local dependency:

npm install bitrix24-tasks-mcp-server

Configuration

Set webhook URL:

export BITRIX24_WEBHOOK_URL="https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"

Required webhook scopes:

• task
• tasks_extended
• sonet_group
• disk (required for attaching images/files to tasks and comments)
• im (required for task chat comments on the new task card)
• crm (required for CRM tools)
• user (required to resolve a lead owner by sender email)

Optional environment variables:

• BITRIX24_DISK_FOLDER_ID — target folder ID for uploads. If omitted, the webhook user's disk storage root folder is used.

Attaching and downloading task files

Bitrix24 stores task attachments on Disk. The MCP now uploads files using the two-step Disk flow recommended by Bitrix24: first disk.folder.uploadfile is called without fileContent to obtain uploadUrl, then the binary is sent to that URL as multipart/form-data. After that the file is attached to the task with tasks.task.files.attach (fallback: UF_TASK_WEBDAV_FILES on tasks.task.update).

Download resolves files via disk.file.get when a Disk FILE_ID is known (avoids browser SSO login pages from chat downloadUrl). Otherwise uses task.item.getfiles metadata. File IDs are collected from:

• UF_TASK_WEBDAV_FILES (tokens like n186771)
• [disk file id=n186771] / [disk file id=151641] markers in the task description (n prefix = FILE_ID, without prefix = ATTACHMENT_ID)

Tools:

• bitrix24_get_task — task fields, comments (chat or legacy), and attachments in one call (images as MCP image content)
• bitrix24_get_task_files — download only task-linked files (lower-level; same Disk download path)
• bitrix24_attach_files_to_task — attach one or more local files to an existing task
• bitrix24_create_task — optional filePaths array to attach files right after task creation

Example — fetch task with comments and screenshots (preferred):

{
  "id": "100265",
  "includeComments": true,
  "includeTaskFiles": true,
  "includeCommentAttachments": true,
  "imagesOnly": false,
  "saveToDirectory": "/tmp/bitrix-task-100265"
}

Legacy tool bitrix24_get_task_comments still works if called by name but is not listed in MCP tools (use bitrix24_get_task instead).

Example — post comment with local files:

{
  "taskId": "100173",
  "text": "См. вложение",
  "filePaths": ["/absolute/path/to/screenshot.png"],
  "preferApi": "auto"
}

Required webhook scopes for comments: task, im, disk.

Example — fetch images from task 100173:

{
  "taskId": "100173",
  "imagesOnly": true
}

Optional: save all files to a local folder:

{
  "taskId": "100173",
  "saveToDirectory": "/tmp/bitrix24-task-100173"
}

Example MCP call:

{
  "taskId": "100689",
  "filePaths": ["/absolute/path/to/schema.png"]
}

Local development in Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/Users/ruslan/Project/bitrix24-mcp-server/build/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/",
        "BITRIX24_DISK_FOLDER_ID": "1739"
      }
    }
  }
}

Available tools

Tasks

• bitrix24_create_task - Create a new task
• bitrix24_create_task supports optional checklist parameter to add checklist items during task creation
• bitrix24_create_task supports optional parentTaskId for parent/subtask linkage
• bitrix24_get_task - Get task by ID with comments and attachments (chat im + Disk download)
• bitrix24_add_task_comment - Post comment via chat (tasks.task.chat.message.send / im.disk.file.commit) or legacy task.commentitem.add
• bitrix24_list_tasks - List tasks (by default only tasks of current webhook user)
• bitrix24_get_latest_tasks - Get latest tasks by creation date
• bitrix24_get_tasks_from_date_range - Get tasks created in a date range
• bitrix24_update_task - Update an existing task
• bitrix24_update_task supports parentTaskId to change parent linkage
• bitrix24_update_task_custom_fields - Update one or more UF_TASK_* fields with read-before-write protection and read-back verification
• bitrix24_get_task_stages - Get Kanban/My Plan stages for a group or user plan
• bitrix24_can_move_task_in_stages - Check whether tasks can be moved in a group/user stage board
• bitrix24_move_task_to_stage - Move a task to another Kanban/My Plan stage by stageId or by stageName + entityId
• bitrix24_get_task_files - Download task attachments from Bitrix24 Disk (images returned as MCP image content)
• bitrix24_attach_files_to_task - Upload local files and attach them to a task
• bitrix24_create_task supports optional filePaths to attach files during creation
• bitrix24_add_task_checklist_item - Add checklist item to task
• bitrix24_list_task_checklist_items - List checklist items in task
• bitrix24_update_task_checklist_item - Update checklist item in task
• bitrix24_delete_task_checklist_item - Delete checklist item from task
• bitrix24_get_task_dependencies - Get dependency IDs for task (DEPENDS_ON)
• bitrix24_add_task_dependency - Create dependency link between tasks
• bitrix24_delete_task_dependency - Remove dependency link between tasks

Example — fill an empty user field and a numeric field:

{
  "taskId": "43691",
  "fields": {
    "UF_TASK_DECISION_MAKER": "42",
    "UF_TASK_BUDGET": 150000
  }
}

Populated fields are protected by default. Pass "overwriteExisting": true only when an existing value must intentionally be replaced. Field values may be scalars, arrays, objects, or null; the server updates only changed fields and verifies every write.

Projects

• bitrix24_create_project - Create a project/workgroup
• bitrix24_get_project - Get project by ID
• bitrix24_list_projects - List projects/workgroups
• bitrix24_update_project - Update project/workgroup

Search and diagnostics

• bitrix24_search_tasks_projects - Search in task and project titles/descriptions
• bitrix24_validate_webhook - Validate webhook connectivity
• bitrix24_diagnose_permissions - Check current webhook scopes and access status

Users

• bitrix24_get_user - Get user by ID
• bitrix24_get_all_users - Get all users
• bitrix24_find_users_by_full_name - Find an active user by exact normalized full name, with optional email-domain filtering and explicit none/unique/ambiguous status
• bitrix24_resolve_user_names - Resolve user IDs to display names

CRM mail-to-lead primitives

• bitrix24_get_crm_sources - Read CRM source codes and labels
• bitrix24_get_crm_lead_stages - Read lead stage codes and semantics, including NEW
• bitrix24_get_crm_fields - Read standard and custom field schemas for leads, companies, or contacts, with required/read-only flags and enumeration IDs
• bitrix24_get_crm_user_fields - Read only UF_CRM_* schemas, optionally selecting exact codes
• bitrix24_find_crm_lead_by_message_id - Read-only lookup of a previous CRM write with none/unique/ambiguous result
• bitrix24_find_crm_user_by_email - Find an active employee by exact sender email; optionally return a configured fallback user ID
• bitrix24_find_crm_company - Search sequentially by INN, phone, email, and exact normalized company title
• bitrix24_resolve_or_create_crm_company - Reuse a unique company, return candidates for manual choice, or create a draft company
• bitrix24_find_crm_contact - Search a client contact by phone and email
• bitrix24_resolve_or_create_crm_contact - Reuse or create a contact only when client contact data exists
• bitrix24_create_crm_lead_idempotent - Create and verify a NEW lead using a Message-ID lookup and same-host serialization
• bitrix24_get_crm_entity - Read a lead, company, or contact and return its card URL

Set BITRIX24_TOOL_PROFILE=crm to expose only these CRM tools. The default full profile exposes both task and CRM tools.

CRM metadata discovery was added in 1.8.0. Version 1.7.0 cannot read sources, lead stages or field definitions through MCP, even with a correctly configured webhook. After upgrading, restart the MCP process and refresh the client's tools/list cache. Use crm or full; workflow exposes task tools only.

The idempotent lead tool requires the configured Bitrix24 field codes for Message-ID and the external process run ID. It first searches by Message-ID, then creates the lead, and finally reads it back. If the create response is lost, it searches again before deciding whether the operation failed. The caller must send the full source email in comments, the discovered mail source code in sourceId, and a resolved employee or fallback in assignedById.

Workers on separate hosts still require orchestration-level serialization. An uncertain network failure followed by an empty lookup is not proof that the write failed; reconcile the operation before authorizing another create.

See CRM mail-to-lead integration for setup and the expected call sequence.

Local development

npm install
npm run build
npm run dev

Publish to npm

npm run build
npm pack --dry-run
npm publish