scrm-mcp-xyt 1.0.0

MCP Server for SCRM (xyt) Integration

SCRM MCP Server

基于 xyt SCRM 系统的 MCP 服务，为 AI 助手提供企业微信数据访问能力。

功能特性

会话存档

• ✅ 会话消息查询和搜索
• ✅ 支持单聊、群聊、内外部联系人会话
• ✅ 全文检索功能
• ✅ 会话权限管理

企微基础数据（已同步到 SCRM）

• ✅ 员工列表查询 - 获取企微员工信息和 weUserId
• ✅ 部门列表查询 - 获取组织架构
• ✅ 客户列表/搜索 - 外部联系人搜索和列表
• ✅ 客户详情/画像 - 客户完整档案、标签、跟进状态
• ✅ 客户标签管理 - 标签组和标签列表
• ✅ 客户群管理 - 群列表、群详情、群成员
• ✅ 跟进记录查询 - 销售跟进历史
• ✅ 客户轨迹查询 - 互动行为轨迹
• ✅ 企业动态查询 - 全公司客户活动流
• ✅ 离职员工管理 - 离职员工列表
• ✅ 任务管理 - 待办/历史任务

复合场景查询

• ✅ 通过客户姓名直接获取消息（支持时间筛选）
• ✅ 通过客户姓名获取完整档案（含详情+跟进+轨迹）
• ✅ 通过员工姓名获取其跟进数据
• ✅ 获取群聊时间范围内的消息
• ✅ 通过成员名称搜索群会话记录

快速开始

1. 安装 Python 3.10+

确保已安装 Python 3.10 或更高版本。

2. 克隆并安装项目

cd scrm-mcp-xyt
pip install -e .

3. 配置 SCRM 连接

创建 scrm_config.json 配置文件：

{
  "base_url": "http://your-scrm-gateway:8080",
  "access_key": "your-access-key",
  "secret_key": "your-secret-key-md5-encrypted"
}

说明：

• access_key: 从 SCRM 系统生成的 Access Key
• secret_key: Secret Key 的 MD5 加密值（32 位小写）
• AK/SK 认证无需验证码，适合自动化场景

或者使用环境变量：

export SCRM_URL="http://your-scrm-gateway:8080"
export SCRM_ACCESS_KEY="your-access-key"
export SCRM_SECRET_KEY="your-secret-key-md5"

4. 运行服务器

python run_server.py

或使用命令行入口：

scrm-mcp-xyt

5. 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "scrm-mcp-xyt": {
      "command": "python",
      "args": ["/path/to/scrm-mcp-xyt/run_server.py"],
      "env": {
        "SCRM_URL": "http://your-scrm-gateway:8080",
        "SCRM_ACCESS_KEY": "your-access-key",
        "SCRM_SECRET_KEY": "your-secret-key-md5"
      }
    }
  }
}

可用的 MCP Tools

会话消息查询

1. get_chat_messages - 获取会话消息列表

   • 参数：
     • from_id (可选): 发送者 ID
     • start_time (可选): 开始时间
     • end_time (可选): 结束时间
     • page_num: 页码 (默认 1)
     • page_size: 每页大小 (默认 10)

2. get_chat_detail - 获取消息详细信息

   • 参数：
     • msg_id: 消息 ID

3. search_messages - 全文检索消息

   • 参数：
     • keyword: 搜索关键词
     • msg_type (可选): 消息类型
     • start_time (可选): 开始时间
     • end_time (可选): 结束时间
     • page_num: 页码
     • page_size: 每页大小

会话列表查询

4. get_external_chat_list - 获取外部联系人会话

   • 参数：
     • from_id: 外部联系人 ID
     • page_num: 页码
     • page_size: 每页大小

5. get_internal_chat_list - 获取内部用户会话

   • 参数：
     • from_id: 内部用户 ID
     • page_num: 页码
     • page_size: 每页大小

6. get_group_chat_list - 获取群聊会话

   • 参数：
     • from_id: 群聊 ID 或用户 ID
     • page_num: 页码
     • page_size: 每页大小

7. get_alone_chat_list - 获取单聊会话

   • 参数：
     • page_num: 页码
     • page_size: 每页大小

权限和信息查询

8. get_permit_user_list - 获取有权限的用户列表

9. check_single_agree - 检查单聊同意情况

   • 参数：
     • user_ids: 用户 ID 列表

10. check_room_agree - 检查群聊同意情况

    • 参数：
      • room_id: 群聊房间 ID

11. get_group_chat_info - 获取群聊信息

    • 参数：
      • room_id: 群聊房间 ID

12. get_current_time - 获取当前时间

客户管理 (新增)

13. search_customers_by_name - 通过名称搜索客户

    • 参数：
      • name: 客户姓名关键词（支持模糊匹配）
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 10)

14. list_all_customers - 获取所有客户列表

    • 参数：
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 20)

群聊管理 (新增)

15. search_groups_by_name - 通过名称搜索群聊

    • 参数：
      • name: 群名称关键词（支持模糊匹配）
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 10)

16. list_all_groups - 获取所有群聊列表

    • 参数：
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 20)

17. get_group_members_list - 获取群成员列表

    • 参数：
      • chat_id: 群聊 ID

复合场景查询 (新增)

18. get_customer_messages_by_name - 通过客户姓名获取消息

    • 参数：
      • customer_name: 客户姓名
      • start_time (可选): 开始时间 (格式: YYYY-MM-DD HH:MM:SS)
      • end_time (可选): 结束时间 (格式: YYYY-MM-DD HH:MM:SS)
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 50)
    • 功能：自动搜索客户 → 获取消息 → 时间过滤

19. get_group_messages_with_time - 获取群聊时间范围内的消息

    • 参数：
      • group_id: 群聊 ID
      • start_time (可选): 开始时间
      • end_time (可选): 结束时间
      • member_id (可选): 成员 ID（筛选特定成员）
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 50)

20. search_member_group_messages - 通过成员名称搜索群会话

    • 参数：
      • member_name: 群成员名称
      • group_name (可选): 群名称（限定在特定群内搜索）
      • start_time (可选): 开始时间
      • end_time (可选): 结束时间
      • page_num: 页码 (默认 1)
      • page_size: 每页大小 (默认 50)
    • 功能：自动搜索成员 → 搜索群聊 → 获取消息 → 过滤

MCP Resources

• scrm://config - 获取 SCRM 系统配置信息

使用示例

在 Claude Desktop 或其他支持 MCP 的 AI 助手中，你可以直接使用自然语言询问：

基础查询

• "帮我查询最近的会话记录"
• "搜索包含'合同'关键词的消息"
• "查看某个外部联系人的聊天记录"
• "获取某个群聊的详细信息"

场景化查询 (新增功能)

场景 1：客户消息查询

问：查询客户"郝彦飞"发给我的所有消息

AI 会自动：
1. 搜索客户"郝彦飞"
2. 获取该客户的消息列表
3. 展示消息内容

追加查询：
问：只看最近7天的消息

场景 2：群聊分析

问：查看群聊"新优态AI-测试2"的群成员和最近的聊天记录

AI 会自动：
1. 搜索群聊"新优态AI-测试2"
2. 获取群成员列表
3. 获取群内消息记录

场景 3：获取群聊列表

问：给我看看所有的群聊

AI 会返回：
- 群聊名称列表
- 群ID
- 群主信息

场景 4：获取客户列表

问：显示所有客户

AI 会返回：
- 客户姓名列表
- 客户类型
- 添加时间等

场景 5：特定群聊的成员

问：查看"新优态AI-测试群"的所有成员

AI 会自动：
1. 搜索群聊
2. 获取成员列表
3. 展示成员详情

场景 6：通过名称搜索群聊

问：搜索包含"AI"的群聊

AI 会返回：
- 所有名称包含"AI"的群聊列表

场景 7：成员的群聊记录

问：查找"张三"在群里的所有发言

AI 会自动：
1. 搜索成员"张三"
2. 获取他的群消息
3. 支持指定时间范围和特定群聊

架构说明

本项目采用以下架构：

scrm-mcp-xyt/
├── src/scrm_mcp/
│   ├── __init__.py          # 包初始化
│   ├── __main__.py          # 命令行入口
│   ├── server.py            # MCP 服务器实现
│   └── scrm_client.py       # SCRM REST API 客户端
├── scrm_config.json         # 配置文件
├── run_server.py            # 独立运行脚本
└── pyproject.toml           # 项目配置

核心组件

1. scrm_client.py: REST API 客户端

   • 实现 JWT 认证
   • 封装所有会话存档 API
   • 自动处理 Token 刷新

2. server.py: MCP 服务器

   • 定义所有 MCP Tools
   • 数据模型和类型安全
   • 错误处理和响应格式化

依赖项

• Python >= 3.10
• mcp >= 0.1.1
• requests >= 2.31.0
• httpx >= 0.24.0

开发

安装开发依赖

pip install -e ".[dev]"

代码格式化

black src/
isort src/

类型检查

mypy src/

许可证

MIT License

相关链接

• MCP 协议文档
• xyt GitHub

贡献

欢迎提交 Issue 和 Pull Request！