Bitrix24 Tasks MCP Server

MCP server for Bitrix24 focused on:

• tasks (tasks.task.*)
• projects/workgroups (sonet_group.*)
• users (user.*)

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)

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

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_resolve_user_names - Resolve user IDs to display names

Local development

npm install
npm run build
npm run dev

Publish to npm

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