Bitrix24용 MCP 서버

41개 도구 · ~870개 액션 · Bitrix24 REST 1.0 + 3.0 · 88개 테스트

Bitrix24 플랫폼용 MCP 서버입니다. Bitrix24 REST API(CRM, 작업, 채팅, 파일, 캘린더, HR, 스마트 프로세스, 메일, 전화 통신, 워크플로우, 이벤트, 오픈 라인, 채팅 봇, 문서 생성기, 견적, 통화, 웹폼, 추적, 재고)를 AI 에이전트가 직접 호출할 수 있는 41개 도구로 래핑합니다 — 그리고 포털에서 실제 호출을 실행합니다(공식 Bitrix24 MCP는 문서만 제공하는 것과 달리).

설치 · MCP 클라이언트 설정 · 기능 · 도구 · 시나리오 · 개발 · npm 패키지

언어: English · Русский

포털 및 구독

이 MCP 서버는 Bitrix24 REST API를 래핑합니다. Bitrix24는 올인원 워크스페이스입니다: CRM, 작업, 프로젝트, 채팅, 화상 통화, 문서, 메일, 캘린더, HR, 비즈니스 프로세스, 전화 통신 등이 포함됩니다. 클라우드(*.bitrix24.ru / *.bitrix24.com) 및 온프레미스로 제공됩니다.

⚠️ 이 서버를 사용하려면 Bitrix24 포털이 필요합니다. 인바운드 웹훅(BX24_WEBHOOK_URL) 또는 OAuth 애플리케이션 (BX24_DOMAIN + BX24_CLIENT_ID + BX24_CLIENT_SECRET + BX24_REFRESH_TOKEN)이 필요합니다. 포털의 개발자 리소스 → 인바운드 웹훅에서 웹훅을 생성하거나, oauth.bitrix24.ru에서 OAuth 앱을 등록하세요.

➡️ 자세한 내용: bitrix24.com · REST 문서: apidocs.bitrix24.ru

Related MCP server: fast-bitrix24-mcp

호환 API 버전

설치

사전 요구 사항

• Node.js 18+

• 활성화된 Bitrix24 포털(클라우드 또는 온프레미스)

• 인증 자격 증명: 인바운드 웹훅 또는 OAuth 앱(아래 참조)

npm에서 설치

npm install -g mcp-b24
# or run without installing
npx -y mcp-b24

환경 변수

다음 중 하나를 선택할 수 있습니다:

• BX24_WEBHOOK_URL 설정 — 가장 간단하며, 웹훅 생성자 대신 작동합니다. 리프레시가 필요 없습니다. 또는

• BX24_DOMAIN + OAuth 자격 증명 설정 — 서버가 액세스 토큰(수명 약 1시간)을 자동 갱신하고 OAuth 응답의 client_endpoint를 따릅니다.

파괴적 작업 확인

BX24_CONFIRM_DESTRUCTIVE=true가 설정되면, 서버는 파괴적 작업(삭제, 제거, 완료, 나가기, 추방, 취소, 중지, 닫기, 음소거, 바인딩 해제, 지우기, markDeleted, kill 등)을 실행하기 전에 명시적인 confirm: true 매개변수를 요구합니다. 이 매개변수가 없으면 도구는 구조화된 requiresConfirmation 미리보기를 반환하고 실행하지 않으므로, AI 에이전트로 인한 우발적 데이터 손실을 방지합니다. 실행된 모든 파괴적 작업은 JSONL 감사 로그(BX24_AUDIT_LOG)에 기록됩니다. 설정하지 않거나 false인 경우, 파괴적 작업은 확인 없이 실행됩니다(기본값).

MCP 클라이언트 설정

Claude Desktop

claude_desktop_config.json에 추가:

npx(권장):

{
  "mcpServers": {
    "bitrix24": {
      "command": "npx",
      "args": ["-y", "mcp-b24"],
      "env": {
        "BX24_WEBHOOK_URL": "https://portal.bitrix24.ru/rest/1/abcd1234/",
        "BX24_CONFIRM_DESTRUCTIVE": "true"
      }
    }
  }
}

OAuth:

{
  "mcpServers": {
    "bitrix24": {
      "command": "npx",
      "args": ["-y", "mcp-b24"],
      "env": {
        "BX24_MODE": "oauth",
        "BX24_DOMAIN": "portal.bitrix24.ru",
        "BX24_CLIENT_ID": "app.abc123",
        "BX24_CLIENT_SECRET": "******",
        "BX24_REFRESH_TOKEN": "******"
      }
    }
  }
}

Windows — cmd /c 사용:

{
  "mcpServers": {
    "bitrix24": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-b24"],
      "env": { "BX24_WEBHOOK_URL": "https://portal.bitrix24.ru/rest/1/abcd1234/" }
    }
  }
}

Docker:

docker build -t mcp/bitrix24 .

{
  "mcpServers": {
    "bitrix24": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "BX24_WEBHOOK_URL", "mcp/bitrix24"],
      "env": { "BX24_WEBHOOK_URL": "https://portal.bitrix24.ru/rest/1/abcd1234/" }
    }
  }
}

Streamable HTTP:

BX24_TRANSPORT=http BX24_HTTP_PORT=3000 BX24_WEBHOOK_URL="https://..." npx mcp-b24
# serves http://127.0.0.1:3000/mcp

Cursor

.cursor/mcp.json에 추가:

{
  "mcpServers": {
    "bitrix24": {
      "command": "npx",
      "args": ["-y", "mcp-b24"],
      "env": { "BX24_WEBHOOK_URL": "https://portal.bitrix24.ru/rest/1/abcd1234/" }
    }
  }
}

VS Code

.vscode/mcp.json에 추가(참고: 최상위 키는 mcpServers가 아닌 servers입니다):

{
  "servers": {
    "bitrix24": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-b24"],
      "env": { "BX24_WEBHOOK_URL": "https://portal.bitrix24.ru/rest/1/abcd1234/" }
    }
  }
}

Codex CLI

codex mcp add bitrix24 --env BX24_WEBHOOK_URL=https://portal.bitrix24.ru/rest/1/abcd1234/ -- npx -y mcp-b24

소스에서

git clone https://github.com/kostikpenzin/mcp_b24.git
cd mcp_b24
npm install
npm run build

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_b24/dist/index.js"],
      "env": { "BX24_WEBHOOK_URL": "https://portal.bitrix24.ru/rest/1/abcd1234/" }
    }
  }
}

도구 개요

41개 도구, ~870개 액션

각 도메인 도구는 액션 기반입니다: action 열거형이 작업을 선택합니다 (예: action: "add", "list", "update", "delete"). 전체 액션 목록: docs/en/TOOLS_REFERENCE.md (RU: docs/ru/).

기능

MCP 서버는 러시아어와 영어의 자연어를 이해합니다. 도구 이름이나 액션 열거형을 알 필요가 없습니다 — 원하는 것을 평범한 언어로 설명하면 AI 에이전트가 올바른 도구와 액션에 매핑합니다.

할 수 있는 작업

• CRM — 리드, 연락처, 회사, 딜, 견적 생성/찾기/업데이트; 파이프라인 간 딜 이동; 활동 관리 (전화/회의); 상품 행; 사용자 정의 필드; 결제 정보 + 은행 정보; 중복 찾기 및 병합; 스마트 프로세스; 문서 생성; 통화; 웹폼; 트래킹; 주소; 콜 리스트; 자동화 트리거; 단계 기록

• 작업 및 프로젝트 — 작업 생성, 완료, 위임, 연기; 체크리스트; 댓글; 경과 시간; 플로우; 칸반 단계; 플래너; 종속성; 사용자 필드; 그룹/프로젝트 + 주제 관리

• 채팅 및 메신저 — 채팅 생성, 구성원 추가/제거, 메시지 보내기/편집/삭제, 반응, 검색, 카운터, 알림, 최근; 오픈 라인 (구성, 세션, 운영자); 채팅 봇 v2 (등록, 명령, 파일)

• 파일 (디스크) — 파일 업로드/다운로드/이동/복사, 폴더 목록, 버전, 공유, 공개 링크, 권한, 첨부 객체

• 캘린더 — 이벤트, 섹션, 회의, 리소스, 가용성, 설정

• HR 및 조직 — 사용자, 부서, 근무 시간 + 시간 관리 + 네트워크 범위 + 일정, 초대/해고/전환

• 비즈니스 — 범용 목록 + 섹션, 메일 (메시지→작업/이벤트/채팅/CRM 포함), 보고서, 마케팅, 워크플로우 + 로봇/활동 CRUD, 전화 (통화, SIP, voximplant 콜백/정보 통화/TTS/회선/통계), 이벤트

• 상품 카탈로그 — 상품, 섹션, 가격, 가격 유형, 측정 단위, VAT, 비율, 반올림 규칙, 추가 요금, 재고 문서, 상품 속성, 변형 (제안), SKU 헤드, 서비스, 재고 기록 (bizproc), 전화, 이벤트 구독

• 배치 및 일반 — 최대 50개 호출 결합; 이름으로 모든 REST 메서드 호출

보안

• 자격 증명 (웹훅 시크릿, OAuth 토큰)은 AI 에이전트에 절대 노출되지 않으며 도구 결과에 반환되지 않습니다

• 파괴적 작업은 명시적 confirm: true (BX24_CONFIRM_DESTRUCTIVE=true)를 요구할 수 있으며 JSONL 감사 로그에 기록됩니다

• 속도 제한은 토큰 버킷으로 준수됩니다; QUERY_LIMIT_EXCEEDED (503) 및 OPERATION_TIME_LIMIT (429)는 백오프로 재시도됩니다

• 비밀번호 관리 및 인증/로그인 작업은 제외됩니다 — 인증은 환경 변수를 통해 자동으로 처리됩니다

사용 시나리오

1. 리드 생성

사용자: "리드 Ivan Petrov 생성, 전화 +79001234567, 이메일 ivan@example.ru"

AI 에이전트는 bx24_crm_leads를 action: "add" 및 fields = { TITLE: "Ivan Petrov", PHONE: [{ VALUE: "+79001234567", VALUE_TYPE: "WORK" }], EMAIL: [...] }로 호출합니다.

2. 오늘의 내 작업 표시

사용자: "Покажи мои задачи на сегодня"

AI 에이전트는 bx24_tasks를 action: "list"로 호출하고 RESPONSIBLE_ID = current 및 DEADLINE = today로 필터링합니다.

3. 파이프라인 간 딜 이동

사용자: "Передвинь сделку №456 на стадию «В работе»"

AI 에이전트는 bx24_crm_deals를 action: "update"로 호출하고 STAGE_ID를 설정합니다 (단계는 action: "category_list"로 나열 가능).

4. 채팅에 메시지 보내기

사용자: "Напиши в чат «Проект Альфа»: релиз сегодня в 18:00"

AI 에이전트는 bx24_im_chat을 action: "sendMessage"로 호출합니다 (DIALOG_ID = chatNNN, MESSAGE = "…").

5. 파일 업로드 및 링크 공유

사용자: "Загрузи PDF-договор на Диск в папку «Договоры 2026» и скинь ссылку в чат «Партнёры»"

AI 에이전트는: bx24_disk → file_upload, 그 다음 file_getExternalLink, 그 다음 bx24_im_chat → sendMessage를 수행합니다.

6. 승인 워크플로우 시작

사용자: "Запусти бизнес-процесс «Согласование с юристами» для сделки #456"

AI 에이전트는 bx24_workflows를 action: "start", templateId 및 documentId = ["crm", "DEAL", 456]로 호출합니다.

7. 영업 퍼널 분석

당신이 말함: "'판매' 퍼널에 대한 보고서를 작성하세요: 단계별 거래, 평균 체크"

AI 에이전트는 bx24_crm_deals action: "list"(CATEGORY_ID로 필터링)와 bx24_reports action: "funnel_stages"를 호출한 다음 집계합니다.

개발

npm install          # Install dependencies
npm run build        # Compile TypeScript + chmod +x
npm run dev          # Watch mode
npm test             # Run 88 tests (vitest)
npm run test:coverage
npm start            # Run server
docker build -t mcp/bitrix24 .   # Docker image
npm publish          # Publish to npm (auto clean + build + test)

프로젝트 구조

mcp_b24/
├── src/
│   ├── index.ts          # MCP server entry point (transport selection)
│   ├── server.ts         # MCP server: register/list/call + instructions
│   ├── config.ts         # Environment configuration (BX24_*)
│   ├── api-client.ts     # HTTP client: webhook/OAuth, refresh, backoff, token-bucket
│   ├── error.ts          # Error handling
│   ├── types.ts          # Shared types
│   ├── i18n/             # ru.ts, en.ts, index.ts
│   ├── audit/log.ts      # JSONL audit of destructive + auth events
│   ├── utils/            # logger, tokenBucket
│   ├── transport.ts      # stdio + Streamable HTTP
│   └── tools/
│       ├── framework.ts  # Data-driven action-tool framework
│       ├── params.ts     # Reusable param schemas
│       ├── index.ts      # Tool registration (41 tools)
│       ├── batch.ts      # bx24_batch
│       ├── call.ts       # bx24_call (escape-hatch)
│       ├── crm/          # 10 CRM tools
│       ├── collab/       # 7 collab tools
│       ├── org/         # 4 org tools
│       └── biz/          # 7 biz tools
├── docs/                 # en/ + ru/ (USER_GUIDE, SELLER_GUIDE, DEVELOPER_GUIDE, TOOLS_REFERENCE, AUDIT_LOG)
├── i18n/README.ru.md     # Russian README
├── specs/openapi.yaml    # OpenAPI overview
├── Dockerfile            # Multi-stage Docker build
├── docker-compose.yml
├── .env.example
├── LICENSE
├── CHANGELOG.md
├── package.json
└── tsconfig.json

라이선스

MIT

작성자

Penzin Konstantin — GitHub · penzin85@gmail.com