bitrix24-mcp-server

Self-hosted Model Context Protocol server for Bitrix24 CRM and smart-process automations (SPAs). Uses built-in Node.js SQLite (node:sqlite) for zero external database setup.

Features

• Bitrix24 OAuth 2.0: Automatic authorization flow, token refresh, and AES-256-GCM encryption at rest in SQLite.

• MCP OAuth 2.1: Dynamic client registration (DCR), S256 PKCE, and static bearer token (MCP_AUTH_TOKEN) fallback.

• CRM & SPA Discovery: Built-in entities (Lead, Deal, Contact, Company, Invoice) and custom SPAs (crm.type.list), fields, categories/funnels, and stages with schema caching.

• Two-Step Writes: Create, update, and stage-move operations are prepared first and executed only after explicit confirmation (bitrix_confirm_operation).

Related MCP server: BitrixMCP

Quick Start

Requirements: Node.js 22.5+ and a Bitrix24 OAuth local/public application with crm scope.

cp .env.example .env
npm ci
npm run build
npm start

Configure your Bitrix24 local application paths:

Handler path:              https://your-server.example.com/oauth/bitrix/callback
Initial installation path: https://your-server.example.com/oauth/bitrix/install

Connect an MCP Client

Streamable HTTP endpoint:

https://your-server.example.com/mcp

• Claude / Claude Code / Codex (OAuth 2.1):

  claude mcp add --transport http bitrix24 https://your-server.example.com/mcp
  # or
  codex mcp add bitrix24 --url https://your-server.example.com/mcp && codex mcp login bitrix24

• Static Bearer Token:

  {
    "mcpServers": {
      "bitrix24": {
        "url": "https://your-server.example.com/mcp",
        "headers": {
          "Authorization": "Bearer <MCP_AUTH_TOKEN>"
        }
      }
    }
  }

• Stdio: Set MCP_TRANSPORT=stdio and run node dist/index.js.

Available Tools

Read-only:

• bitrix_list_connections, bitrix_discover_portal, bitrix_list_crm_entities, bitrix_describe_entity

• bitrix_list_fields, bitrix_list_categories, bitrix_list_stages, bitrix_refresh_schema_cache

• bitrix_search_items, bitrix_get_item, bitrix_list_users

Write (requires write_with_confirmation mode):

• bitrix_prepare_create_item, bitrix_prepare_update_item, bitrix_prepare_move_item_stage

• bitrix_confirm_operation, bitrix_cancel_operation, bitrix_list_pending_operations

Configuration

Docker (Local)

docker compose up --build

SQLite data is persisted in the sqlite_data volume mounted at /app/data.

Deploy to Dokploy

1. GHCR & GitHub Actions (.github/workflows/deploy.yml):

   • On push to main, GitHub Actions builds and pushes ghcr.io/sergei93/b24-mcp:latest and triggers DOKPLOY_DEPLOY_WEBHOOK.

   • In Dokploy: add GHCR registry (Settings → Registry, PAT with read:packages).

2. Create Compose Service:

   • Create → Compose → GitHub → select repository → set Compose Path to docker-compose.dokploy.yml.

   • Disable auto-deploy on push in Dokploy, copy the Webhook URL from Compose → Webhook, and save it as DOKPLOY_DEPLOY_WEBHOOK in GitHub Repository Secrets.

3. Environment & Domain:

   • Fill required variables in Dokploy Environment (APP_URL, BITRIX_CLIENT_ID, BITRIX_CLIENT_SECRET, MCP_AUTH_TOKEN, TOKEN_ENCRYPTION_KEY, optional BITRIX_PORTAL_DOMAIN).

   • In Domains, point your HTTPS domain to service app on port 3000.