Bitrix24 MCPブリッジ

Claude（MCP）とBitrix24 CRM/タスクを橋渡しするブリッジ。Begetホスティング上に mcp-bitrix.karpovpartners-it.ru で展開しています。

1. なぜこれが必要になったのか

当初はBitrix24に組み込まれている「MCP接続」コネクタ（アプリ aiassistant.bitrix_mcp / マーケットプレイスの「Б24」ボタン）を介してClaudeをBitrix24に接続しようとしました。 しかし、この機能は動作しないことが判明しました：/authorize、/.well-known/oauth-authorization-server、 /.well-known/oauth-protected-resource のエンドポイントは、すべての設定とサブスクリプションが 正常であるにもかかわらず、素のnginx 404を返します。これはBitrix24側のバグ/未完成機能であり、 設定ミスではありません。

回避策として、独自のMCPサーバー（「ブリッジ」）を作成しました。このサーバーは：

• ClaudeからのMCPリクエストをStreamable HTTPプロトコルで受け付けます；

• それらを受信ウェブフック（CRM + タスクのみの権限でBitrix24に作成）を介した 通常のBitrix24 REST API呼び出しに変換します；

• 結果をMCPツール応答としてClaudeに返します。

Related MCP server: fast-bitrix24-mcp

2. アーキテクチャとファイル

Claudeで利用可能なツール

• 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での展開中に遭遇した問題とその解決方法

デバッグログ — 古いNode.jsを使用するBegetや他の共有ホスティングでの再展開時に役立ちます。

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ディスカバリーエンドポイントは、 設定が有効でサブスクリプションがアクティブな状態でも素のnginx 404を返します。 Bitrix24がこれを修正した場合、公式コネクタに切り替えることができます — または、このブリッジを残すこともできます。これも動作し、より多くの制御を提供します （例：コード内でメソッドをCRM＋タスクに直接制限すること）。