AI导哈

CRM集成服务器

Bitrix24 MCP服务器是一个全面的CRM集成解决方案，提供联系人、交易、任务管理等功能，支持AI代理与Bitrix24实例的无缝交互。

  • by yakovpakhomov
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 yakovpakhomov/bitrix24-mcp-server

使用说明

Bitrix24 MCP服务器

用于Bitrix24 CRM集成的全面模型上下文协议（MCP）服务器，使AI代理能够通过一组强大的工具与您的Bitrix224实例无缝交互。

🚀 特性

  • 完整的CRM管理：创建、读取、更新和列出联系人、交易和任务
  • 高级搜索：通过灵活的筛选在所有CRM实体中搜索
  • 速率限制：符合Bitrix24 API限制的内置速率限制
  • 类型安全：具有全面类型定义的完整TypeScript实现
  • 错误处理：强大的错误处理和验证
  • 易于集成：使用Claude Desktop和其他MCP兼容客户端进行简单设置

📋 可用工具

联系人管理

  • bitrix24_create_contact -创建新联系人
  • bitrix24_get_contact -按ID检索联系人
  • bitrix24_list_contacts -使用筛选功能列出联系人
  • bitrix24_update_contact -更新现有联系人

交易管理

  • bitrix24_create_deal -创建新交易
  • bitrix24_get_deal -按ID检索交易
  • bitrix24_list_deals -列表处理过滤
  • bitrix24_update_deal -更新现有交易

任务管理

  • bitrix24_create_task -创建新任务
  • bitrix24_get_task -按ID检索任务
  • bitrix24_list_tasks -列出带有筛选功能的任务
  • bitrix24_update_task -更新现有任务

用户管理

  • bitrix24_get_user -按ID获取用户信息
  • bitrix24_get_all_users -获取系统中所有用户的姓名和详细信息
  • bitrix24_resolve_user_names -将用户ID解析为用户名
  • bitrix24_get_contacts_with_user_names -获取已解析用户名的联系人
  • bitrix24_get_deals_with_user_names -解决用户名问题
  • bitrix24_get_leads_with_user_names -获取已解决用户名的潜在客户
  • bitrix24_get_companies_with_user_names -解析用户名的公司

潜在客户管理

  • bitrix24_create_lead -创建新的潜在客户
  • bitrix24_get_lead -按ID检索潜在客户
  • bitrix24_list_leads -使用筛选功能列出潜在客户
  • bitrix24_get_latest_leads -获取最新线索
  • bitrix24_get_leads_from_date_range -从特定日期范围获取潜在客户
  • bitrix24_update_lead -更新现有潜在客户

公司管理层

  • bitrix24_create_company -创建新公司
  • bitrix24_get_company -按ID检索公司
  • bitrix24_list_companies -列出具有筛选功能的公司
  • bitrix24_get_latest_companies -获取最新公司
  • bitrix24_get_companies_from_date_range -从特定日期范围获取公司
  • bitrix24_update_company -更新现有公司

增强的交易过滤

  • bitrix24_get_deal_pipelines -获取所有交易渠道/类别
  • bitrix24_get_deal_stages -获得管道交易阶段
  • bitrix24_filter_deals_by_pipeline -按渠道筛选交易
  • bitrix24_filter_deals_by_budget -按预算范围筛选交易
  • bitrix24_filter_deals_by_status -按阶段/状态筛选交易

公用事业

  • bitrix24_search_crm -跨CRM实体搜索
  • bitrix24_get_current_user -获取当前用户信息
  • bitrix24_validate_webhook -验证webhook连接
  • bitrix24_diagnose_permissions -诊断webhook权限
  • bitrix24_check_crm_settings -检查CRM设置和配置
  • bitrix24_test_leads_api -测试引线API端点

销售团队监控

  • bitrix24_monitor_user_activities -监控用户活动（通话、电子邮件、时间线交互、响应时间）
  • bitrix24_get_user_performance_summary -获取包含交易指标和转化率的全面绩效摘要
  • bitrix24_analyze_account_performance -分析特定客户（公司/联系人）的绩效
  • bitrix24_compare_user_performance -比较多个用户之间的性能指标
  • bitrix24_track_deal_progression -通过时间分析跟踪管道阶段的交易进展
  • bitrix24_monitor_sales_activities -监控销售相关活动（任务、跟进、会议）
  • bitrix24_generate_sales_report -生成具有可定制指标的全面销售报告
  • bitrix24_get_team_dashboard -获取实时团队绩效仪表板
  • bitrix24_analyze_customer_engagement -分析客户参与模式和关系健康状况
  • bitrix24_forecast_performance -生成性能预测和预测分析

🛠️ 安装

先决条件

  • Node.js 18+
  • npm或纱线
  • Bitrix24 webhook URL

设置

  1. 克隆和安装依赖关系：
git clone <repository-url>
cd bitrix24-mcp-server
npm install
  1. 配置环境：
cp .env.example .env
# Edit .env with your Bitrix24 webhook URL
  1. 构建项目：
npm run build
  1. 测试连接：
npm test

⚙️ 配置

环境变量

创建一个 .env 包含以下变量的文件：

BITRIX24_WEBHOOK_URL=https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/
NODE_ENV=development
LOG_LEVEL=info

Bitrix24 Webhook设置

  1. 转到您的Bitrix24实例
  2. 导航至 应用程序 → 网络钩子
  3. 创建一个 传入webhook
  4. 复制webhook URL（格式： https://domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/)
  5. 为CRM和任务设置适当的权限

🔧 Claude桌面集成

将以下内容添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/path/to/your/bitrix24-mcp-server/build/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"
      }
    }
  }
}

📖 用法示例

创建联系人

Create a new contact named John Smith with email john@example.com and phone +39 123 456 789

与联系人创建交易

Create a new contact for Maria Rossi with email maria@company.com, then create a deal titled "Website Development Project" for €5000 and link it to this contact

管理任务

Create a task titled "Follow up with client" with high priority, deadline tomorrow, and link it to contact ID 123

搜索CRM

Search for all contacts and deals related to "example.com"

🏗️ 发展

项目结构

bitrix24-mcp-server/
├── src/
│   ├── bitrix24/
│   │   └── client.ts          # Bitrix24 API client
│   ├── tools/
│   │   └── index.ts           # MCP tools definitions
│   ├── utils/
│   │   └── logger.ts          # Logging utilities
│   ├── config/
│   │   └── index.ts           # Configuration management
│   └── index.ts               # Main MCP server
├── test/
│   └── integration.test.js    # Integration tests
├── build/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

开发命令

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Run tests
npm test

# Start the server
npm start

添加新工具

  1. 在中定义工具 src/tools/index.ts:
export const newTool: Tool = {
  name: 'bitrix24_new_action',
  description: 'Description of the new action',
  inputSchema: {
    type: 'object',
    properties: {
      // Define parameters
    },
    required: ['requiredParam']
  }
};
  1. 添加执行处理程序：
case 'bitrix24_new_action':
  // Implementation
  return { success: true, result: 'Action completed' };
  1. 添加 allTools 阵列和重建。

🔒 安全考虑

  • Webhook安全：将您的webhook URL保密并定期轮换
  • 环境变量：从不承诺 .env 文件到版本控制
  • 速率限制客户端内置了速率限制功能（每秒2个请求）
  • 错误处理：敏感信息不会在错误消息中暴露

🐛 故障排除

常见问题

“Webhook验证失败”

  • 验证您的webhook URL是否正确
  • 检查webhook是否具有适当的权限
  • 确保您的Bitrix24实例可访问

“找不到模块”错误

  • 跑 npm install 安装依赖项
  • 确保您已使用以下工具构建了项目 npm run build

速率限制错误

  • 客户端自动处理速率限制
  • 如果您看到持续的速率限制错误，请考虑降低请求频率

调试模式

集 NODE_ENV=development 和 LOG_LEVEL=debug 在你的 .env 详细日志记录文件。

📝 api参考

Bitrix24客户端方法

联系人

  • createContact(contact: BitrixContact): Promise<string>
  • getContact(id: string): Promise<BitrixContact>
  • updateContact(id: string, contact: Partial<BitrixContact>): Promise<boolean>
  • listContacts(params?: ListParams): Promise<BitrixContact[]>

交易

  • createDeal(deal: BitrixDeal): Promise<string>
  • getDeal(id: string): Promise<BitrixDeal>
  • updateDeal(id: string, deal: Partial<BitrixDeal>): Promise<boolean>
  • listDeals(params?: ListParams): Promise<BitrixDeal[]>

任务

  • createTask(task: BitrixTask): Promise<string>
  • getTask(id: string): Promise<BitrixTask>
  • updateTask(id: string, task: Partial<BitrixTask>): Promise<boolean>
  • listTasks(params?: TaskListParams): Promise<BitrixTask[]>

用户

  • getUser(userId: string): Promise<any>
  • getAllUsers(): Promise<any[]>
  • getUsersByIds(userIds: string[]): Promise<any[]>
  • resolveUserNames(userIds: string[]): Promise<Record<string, string>>
  • enhanceWithUserNames<T>(items: T[], userIdFields?: string[]): Promise<T[]>

公用事业

  • getCurrentUser(): Promise<any>
  • searchCRM(query: string, entityTypes?: string[]): Promise<any>
  • validateWebhook(): Promise<boolean>

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🆘 支持

对于问题和疑问：

  1. 检查故障排除部分
  2. 查看Bitrix24 API文档
  3. 在GitHub上打开一个问题

内置于❤️ 面向人工智能自动化社区

相关 MCP