bitrix24-mcp-server

MCP server for managing Bitrix24 tasks via a personal webhook.
Designed for non-admin users who want to track, filter and edit their own tasks through any MCP-compatible AI client (Claude Desktop, VS Code, etc.).

Prerequisites

• Node.js ≥ 20
• A Bitrix24 incoming webhook with task permissions

Setup

npm install
npm run build

Configuration

Environment variable

| Variable | Description | Example | |---|---|---| | BITRIX24_WEBHOOK_URL | Full webhook URL (trailing slash optional) | https://mycompany.bitrix24.ru/rest/42/abc123xyz/ |

The user ID is extracted automatically from the webhook URL.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/absolute/path/to/bitrix24-mcp-server/dist/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://mycompany.bitrix24.ru/rest/42/abc123xyz/"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "bitrix24": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/bitrix24-mcp-server/dist/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://mycompany.bitrix24.ru/rest/42/abc123xyz/"
      }
    }
  }
}

Available Tools

Read tools

| Tool | Description | |---|---| | bitrix_list_tasks | List and filter tasks with pagination | | bitrix_get_task | Get full task details, optionally with checklist, subtasks and custom fields | | bitrix_get_my_tasks | Get tasks where the webhook user is responsible | | bitrix_get_checklist | Get all checklist items for a task | | bitrix_list_task_custom_fields | List all UF_* custom fields with human-readable labels |

Write tools

| Tool | Description | |---|---| | bitrix_create_task | Create a new task (with optional custom UF_* fields) | | bitrix_update_task | Update task fields (title, description, deadline, priority, tags, responsible, custom fields) | | bitrix_set_task_status | Change task status via workflow actions | | bitrix_add_checklist_item | Add a checklist item to a task | | bitrix_toggle_checklist_item | Mark a checklist item as complete or incomplete |

Batch tools

| Tool | Description | |---|---| | bitrix_batch_set_status | Change status on multiple tasks in one request (up to 50) | | bitrix_batch_get_tasks | Get full details on multiple tasks in one request (up to 50) |

Custom fields workflow

Bitrix24 supports user-defined fields (UF_*) on tasks. The typical agent workflow:

1. bitrix_list_task_custom_fields — discover available fields and their human-readable labels
   (e.g. UF_AUTO_257747812215 → "RICE")
2. bitrix_get_task(taskId, include_custom_fields: true) — read current field values
3. bitrix_create_task or bitrix_update_task with custom_fields: { "UF_AUTO_257747812215": ["2","4","5","1"] }

Filter reference (bitrix_list_tasks)

| Parameter | Values | |---|---| | status | "2" Pending, "3" In Progress, "4" Awaiting Control, "5" Completed, "6" Deferred, "-1" Overdue, "-2" Unviewed, "-3" Almost Overdue | | priority | "0" Low, "1" Medium, "2" High | | sort_by | ID, DEADLINE, CREATED_DATE, CHANGED_DATE, PRIORITY | | sort_order | asc, desc |

Status actions (bitrix_set_task_status)

| Action | Resulting status | |---|---| | start | In Progress (3) | | complete | Completed (5) | | pause | Pending (2) | | defer | Deferred (6) | | renew | Pending (2) — reverts completed |

Development

npm run dev      # watch mode (TypeScript compiler)
npx @modelcontextprotocol/inspector dist/index.js   # interactive tool explorer

Set the env variable before running inspector:

BITRIX24_WEBHOOK_URL=https://... npx @modelcontextprotocol/inspector dist/index.js