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 服务器（「桥接器」），它：

• 通过 Streamable HTTP 协议接收来自 Claude 的 MCP 请求；

• 通过入站 Webhook（在 Bitrix24 中创建，仅授予 CRM + 任务权限）将其转换为 对 Bitrix24 普通 REST API 的调用；

• 以 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）——这是为了防止 Webhook 将来 获得更广泛的权限。

3. 认证 / 安全

Claude 界面中的自定义 MCP 连接器没有用于任意 HTTP 请求头的字段——只有 URL（+ 可选的 OAuth Client ID/Secret）。因此，密钥不是放在 Authorization 请求头中，而是嵌入在 URL 路径中：

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

密钥和 Bitrix24 Webhook 地址仅存储在服务器上的生产 .htaccess 以及项目所有者的私有副本中——它们有意未提交到此仓库（见 .gitignore）。任何 从 URL 中得知密钥的人，都将在 Webhook 权限范围内获得对 Bitrix24 CRM 和任务的访问权限。

4. 分步工作原理

1. Claude 打开 MCP 连接器 → POST 到 /mcp/<密钥>，请求体为 {"method":"initialize", ...}。

2. server.mjs 中的 Express 路由创建一个新的 McpServer （StreamableHTTPServerTransport，sessionIdGenerator: undefined — 无会话保存的服务器，每个请求相互独立）。

3. Claude 调用 tools/list，然后调用 tools/call 并指定具体 工具（例如 bitrix24_list_crm）。

4. server.mjs 调用 bitrixCall(method, params)，该方法对 https://<门户>.bitrix24.ru/rest/<id>/<webhook>/<方法>.json 执行 fetch()。

5. Bitrix24 的响应被包装为 MCP 格式并返回给 Claude。

5. 从零开始部署

1. 在 Bitrix24 中创建入站 Webhook：设置 → 开发者 → 其他 → 入站 Webhook。权限 — 最少 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，并 手动补充 Node 16 中缺失的、现代依赖（@modelcontextprotocol/sdk、Express 5） 所需的全局对象：

• 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 之前 （通过 await import(...) 完成，而不是文件顶部的普通 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 扩展名 — 始终是 ES 模块，与 package.json 无关），而 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+任务）。