Bitrix24 MCP Bridge

Claude(MCP)와 Bitrix24 CRM/작업 간의 브리지. Beget 호스팅에 mcp-bitrix.karpovpartners-it.ru 주소로 배포되어 있습니다.

1. 왜 필요했나

처음에는 Bitrix24에 내장된 커넥터인 «МСР-подключения»(마켓플레이스의 aiassistant.bitrix_mcp 앱 / «Б24» 버튼)을 통해 Claude를 Bitrix24에 연결하려 했습니다. 그런데 이 기능은 작동하지 않는 것으로 드러났습니다: /authorize, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource 엔드포인트가 모든 설정과 구독이 정상인데도 빈 nginx 404를 반환합니다. 이는 설정 오류가 아니라 Bitrix24 측의 버그/미완성 기능입니다.

우회 방법으로 자체 MCP 서버(«브리지»)를 작성했으며, 그 역할은 다음과 같습니다:

• Streamable HTTP 프로토콜로 Claude의 MCP 요청을 수신합니다;

• 그 요청들을 인바운드 웹훅을 통해 일반 Bitrix24 REST API 호출로 변환합니다(CRM + 작업 권한만 있는 웹훅으로 Bitrix24에서 생성됨);

• 결과를 MCP 도구 응답 형태로 Claude에 반환합니다.

Related MCP server: fast-bitrix24-mcp

2. 아키텍처 및 파일

Claude에서 사용할 수 있는 도구(tools)

• bitrix24_call — crm.*, task.*, tasks.*, user.current, profile 등 모든 메서드를 직접 호출(이스케이프 해치).

• bitrix24_list_crm / bitrix24_get_crm / bitrix24_add_crm / bitrix24_update_crm — CRM 레코드 목록/조회/생성/업데이트(lead, deal, contact, company).

• bitrix24_list_tasks / bitrix24_add_task / bitrix24_update_task / bitrix24_complete_task — 작업 처리.

서버는 호출되는 Bitrix24 메서드를 crm., task., tasks., user.current, profile 접두사로 엄격히 제한합니다(server.mjs의 ALLOWED_METHOD_PREFIXES 참조). 이는 웹훅에 나중에 더 넓은 권한이 부여될 경우를 대비한 보호 장치입니다.

3. 인증 / 보안

Claude 인터페이스의 사용자 지정 MCP 커넥터에는 임의 HTTP 헤더를 넣을 필드가 없습니다. URL만 있습니다(+ 선택적으로 OAuth Client ID/Secret). 따라서 Authorization 헤더 대신 비밀값이 URL 경로에 포함되어 있습니다:

https://mcp-bitrix.karpovpartners-it.ru/mcp/<секрет>

비밀값과 Bitrix24 웹훅 주소는 서버의 운영 .htaccess와 프로젝트 소유자의 개인 복사본에만 저장됩니다 — 이 저장소에 의도적으로 커밋되지 않았습니다(.gitignore 참조). URL에서 비밀값을 알게 된 사람은 웹훅 권한 범위 내에서 Bitrix24의 CRM 및 작업에 접근할 수 있습니다.

4. 단계별 작동 방식

1. Claude가 MCP 커넥터를 엽니다 → /mcp/<секрет>으로 본문 {"method":"initialize", ...}과 함께 POST 요청을 보냅니다.

2. server.mjs의 Express 라우트가 새 McpServer를 생성합니다(StreamableHTTPServerTransport, sessionIdGenerator: undefined — 세션을 저장하지 않는 서버로, 각 요청은 독립적입니다).

3. Claude가 tools/list를 호출한 다음 특정 도구(예: bitrix24_list_crm)로 tools/call을 호출합니다.

4. server.mjs가 bitrixCall(method, params)를 호출하고, 이 함수는 https://<портал>.bitrix24.ru/rest/<id>/<вебхук>/<метод>.json에 대해 fetch()를 수행합니다.

5. Bitrix24의 응답은 MCP 형식으로 감싸져 Claude로 다시 전송됩니다.

5. 처음부터 배포하기

1. Bitrix24에서 인바운드 웹훅 생성: 설정 → 개발자 → 기타 → 인바운드 웹훅. 권한은 최소 CRM + 작업.

2. 저장소를 서버의 사이트 디렉토리(public_html — 도메인/하위 도메인)에 클론합니다.

3. 이 디렉토리에서 npm install 실행(express, zod, @modelcontextprotocol/sdk, undici 설치).

4. .htaccess.example을 .htaccess로 복사하고 실제 BITRIX_WEBHOOK_URL 및 MCP_PATH_SECRET를 입력합니다.

5. Beget에서: mkdir tmp && touch tmp/restart.txt — 코드 변경 후 앱을 재시작하기 위한 Passenger 명령입니다.

6. Beget 패널에서: «사이트» → 해당 사이트 → «⋮» → «도메인 연결» — 이 단계가 없으면 Apache는 코드에 접근조차 시도하지 않습니다(섹션 6.2 참조 — 잊기 쉽고 오류가 명확하지 않습니다).

6. Beget 배포 시 겪은 문제점과 해결 방법

디버깅 기록 — Beget이나 오래된 Node.js를 사용하는 다른 공유 호스팅에 다시 배포할 때 유용합니다.

6.1. Beget의 Node.js — 버전 16.20.2, 너무 오래됨

Beget 측(Ubuntu 18.04, glibc 2.27)에서는 Node 18+ 공식 빌드가 실행되지 않습니다(GLIBC_2.28' not found). Node 16.20.2를 유지하고, 최신 의존성(@modelcontextprotocol/sdk, Express 5)에 필요한 Node 16에 없는 전역 객체를 수동으로 추가해야 했습니다:

• fetch, Headers, Request, Response — undici 패키지를 통해.

• crypto (Web Crypto API, crypto.randomUUID()) — 내장 node:crypto(webcrypto)를 통해.

• ReadableStream, WritableStream, TransformStream — 내장 node:stream/web를 통해.

• structuredClone, MessageChannel/MessagePort — 만일을 대비해 node:v8 및 node:worker_threads를 통해.

이 모든 것은 server.mjs의 맨 처음, Express 및 MCP SDK를 임포트하기 전에 수행됩니다(파일 상단의 일반 import가 아닌 await import(...)로 처리 — 이유는 다음 항목 참조).

6.2. 도메인이 사이트 폴더에 «연결»되지 않음

코드를 서버에 업로드한 후 사이트는 앱 대신 Beget의 «도메인이 서버의 디렉토리에 연결되지 않았습니다»라는 안내 페이지를 표시했습니다. 사이트 폴더를 만들고 파일을 업로드하는 것만으로는 부족합니다. 패널에서 도메인을 별도로 «연결»해야 합니다: «사이트» → 해당 사이트 → «⋮» → «도메인 연결». 놓치기 쉬운 명확하지 않은 단계입니다.

6.3. ERR_REQUIRE_ESM: Passenger가 ES 모듈을 로드할 수 없음

Beget의 Passenger(구버전, passenger40)는 require()로 시작 파일을 실행하는데, Node의 require()는 원칙적으로 ES 모듈(import/export, package.json의 type: module)을 로드할 수 없습니다. server.mjs는 파일 최상위 레벨에서 await를 사용합니다 — 이는 ES 모듈에서만 가능합니다.

해결책: package.json에 "type": "module"이 없습니다(기본적으로 .js는 CommonJS). 코드 자체는 .mjs 확장자 파일에 있습니다(.mjs 확장자는 package.json과 관계없이 항상 ES 모듈입니다). Passenger의 진입점은 app.js — 아주 작은 CommonJS 파일입니다:

// app.js
import('./server.mjs').catch((err) => {
  console.error('Failed to start server:', err);
  process.exit(1);
});

require()는 app.js를 문제없이 로드하고(일반 CommonJS), 그 안의 동적 import()(선언이 아닌 함수)는 ES 모듈 server.mjs를 비동기적으로 로드할 수 있습니다.

6.4. URL 경로의 비밀값

MCP_PATH_SECRET — 임의 문자열(예: Python의 secrets.token_urlsafe(32), 또는 브라우저 콘솔의 crypto.randomUUID() + crypto.randomUUID()). 비밀값을 재발급해야 한다면 새로 생성하고 서버의 .htaccess와 Claude의 커넥터 설정에서 업데이트하세요.

7. Claude에서 연결하는 방법

1. claude.ai → 설정 → Connectors → Add custom connector.

2. Name: Bitrix24(아무 이름이나).

3. Remote MCP server URL: https://mcp-bitrix.karpovpartners-it.ru/mcp/<секрет>

4. OAuth Client ID / Secret — 비워 두세요. 필요 없습니다(인증이 이미 URL에 포함되어 있습니다).

5. 저장하고 채팅에서 커넥터를 활성화하세요.

8. 미해결 질문 — Bitrix24 네이티브 MCP 커넥터

Bitrix24 지원팀에 고장난 네이티브 MCP 커넥터(마켓플레이스의 «Б24»)에 대해 문의할 만합니다: 설정이 활성화되고 구독이 유효한데도 /authorize 및 표준 OAuth-discovery 엔드포인트가 빈 nginx 404를 반환합니다. Bitrix24가 이를 고치면 공식 커넥터로 전환할 수 있습니다. 또는 이 브리지를 유지해도 됩니다. 이것도 작동하며 더 많은 제어 기능을 제공합니다(예: 코드에서 직접 CRM+작업으로 메서드 제한).