即时通讯服务器

环信IM MCP服务器是一个完整集成了环信即时通讯RESTful API的服务器,提供用户管理、消息管理、群组管理、聊天室管理等功能,适用于需要即时通讯解决方案的应用场景。

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

使用说明

环信IM MCP服务器 - 完整版

这是一个完整集成了环信即时通讯(Easemob IM) RESTful API的MCP (Model Context Protocol) 服务器。涵盖环信IM的所有主要功能,包括用户管理、消息管理、群组管理、聊天室管理、好友关系、黑名单管理、用户属性管理、文件管理等。

🚀 功能特性

✅ 用户管理系统

  • 用户操作: 注册单个/批量用户、获取用户信息、删除用户
  • 用户状态: 获取在线状态、强制下线、修改密码
  • 用户属性: 设置/获取/删除用户自定义属性

✅ 消息管理系统

  • 消息发送: 支持文本、图片、语音、视频、文件、位置、透传、自定义消息
  • 消息操作: 消息撤回、历史消息查询
  • 消息类型: 单聊、群聊、聊天室消息全覆盖

✅ 群组管理系统

  • 群组操作: 创建、获取、修改、删除群组
  • 成员管理: 添加/移除成员、获取成员列表、转让群主
  • 权限管理: 管理员设置、群主转让
  • 黑白名单: 群组黑名单、白名单管理
  • 禁言管理: 单个/批量/全体禁言和解禁

✅ 聊天室管理系统

  • 聊天室操作: 创建、获取、修改、删除聊天室
  • 成员管理: 添加/移除成员、管理员设置
  • 权限控制: 黑白名单、禁言管理
  • 公告管理: 设置和修改聊天室公告

✅ 用户关系管理

  • 好友系统: 添加/删除好友、获取好友列表
  • 黑名单: 添加/移除黑名单、查看黑名单

✅ 文件管理系统

  • 文件操作: 文件上传、下载
  • 文件类型: 支持图片、语音、视频、文档等各种文件类型

✅ 高级特性

  • 自动认证: 智能Token管理和自动刷新
  • 错误处理: 完善的错误处理和中文错误信息
  • API覆盖: 涵盖环信IM REST API的所有主要功能
  • 类型安全: 完整的TypeScript类型定义

📖 环信文档参考

本项目基于环信即时通讯 REST API 开发,详细API文档请参考:

🛠 快速开始

1. 安装依赖

npm install

2. 配置环信应用信息

复制环境变量示例文件:

cp env.example .env

编辑 .env 文件,填入您的环信应用配置信息:

# 环信应用配置 - 在环信控制台获取
EASEMOB_ORG_NAME=your_org_name
EASEMOB_APP_NAME=your_app_name  
EASEMOB_APP_KEY=your_app_key
EASEMOB_APP_SECRET=your_app_secret

# 可选:自定义API域名(默认使用 https://a1.easemob.com)
# EASEMOB_BASE_URL=https://a1.easemob.com

获取配置信息:

  1. 登录环信开发者控制台
  2. 选择您的应用
  3. 在"应用概览"页面获取所需配置信息

3. 编译和启动

# 编译项目
npm run build

# 开发模式启动
npm run dev

# 生产模式启动  
npm start

🔧 完整API功能列表

📱 用户管理API

功能 API方法 描述
注册单个用户 createUser 创建单个环信用户
批量注册用户 createUsers 批量创建环信用户
获取用户信息 getUser 获取指定用户详细信息
获取用户列表 getUserList 分页获取用户列表
删除单个用户 deleteUser 删除指定用户
批量删除用户 deleteUsers 批量删除用户
修改用户密码 changeUserPassword 修改用户登录密码
强制用户下线 disconnectUser 强制指定用户下线
获取用户状态 getUserStatus 查看用户在线状态

💬 消息管理API

功能 API方法 描述
发送消息 sendMessage 发送各种类型消息
获取历史消息 getHistoryMessages 获取聊天历史记录
撤回消息 recallMessage 撤回已发送的消息

📁 文件管理API

功能 API方法 描述
上传文件 uploadFile 上传图片、语音、视频等文件
下载文件 downloadFile 下载文件内容

👥 用户关系API

功能 API方法 描述
添加好友 addContact 添加用户为好友
删除好友 removeContact 从好友列表删除用户
获取好友列表 getContacts 获取用户的好友列表
获取黑名单 getBlockedUsers 获取用户的黑名单列表
添加黑名单 blockUser 将用户添加到黑名单
移除黑名单 unblockUser 从黑名单移除用户

🏷 用户属性API

功能 API方法 描述
设置用户属性 setUserMetadata 设置用户自定义属性
获取用户属性 getUserMetadata 获取用户自定义属性
批量获取属性 batchGetUserMetadata 批量获取多用户属性
删除用户属性 deleteUserMetadata 删除用户自定义属性

👥 群组管理API

功能 API方法 描述
获取群组列表 getGroupList 分页获取所有群组
获取用户群组 getUserJoinedGroups 获取用户加入的群组
获取群组详情 getGroup 获取群组详细信息
创建群组 createGroup 创建新群组
修改群组信息 updateGroup 修改群组基本信息
删除群组 deleteGroup 删除指定群组

👨‍👩‍👧‍👦 群组成员API

功能 API方法 描述
获取群组成员 getGroupMembers 分页获取群组成员列表
添加群组成员 addGroupMember 添加单个用户到群组
批量添加成员 addGroupMembers 批量添加用户到群组
移除群组成员 removeGroupMember 从群组移除单个用户
批量移除成员 removeGroupMembers 从群组批量移除用户
转让群组 transferGroup 转让群主权限
获取群管理员 getGroupAdmins 获取群组管理员列表
添加群管理员 addGroupAdmin 设置群组管理员
移除群管理员 removeGroupAdmin 取消群组管理员

🚫 群组黑白名单API

功能 API方法 描述
获取群组黑名单 getGroupBlockedUsers 查看群组黑名单
添加群组黑名单 addGroupBlockedUsers 批量添加黑名单用户
移除群组黑名单 removeGroupBlockedUsers 批量移除黑名单用户
获取群组白名单 getGroupWhiteUsers 查看群组白名单
添加群组白名单 addGroupWhiteUsers 批量添加白名单用户
移除群组白名单 removeGroupWhiteUsers 批量移除白名单用户

🔇 群组禁言API

功能 API方法 描述
获取禁言列表 getGroupMutedUsers 查看群组禁言用户列表
禁言群组成员 muteGroupMembers 禁言指定群组成员
解除成员禁言 unmuteGroupMembers 解除群组成员禁言
禁言全体成员 muteAllGroupMembers 一键禁言全体成员
解除全员禁言 unmuteAllGroupMembers 一键解除全员禁言

🏠 聊天室管理API

功能 API方法 描述
获取聊天室列表 getChatroomList 分页获取所有聊天室
获取用户聊天室 getUserJoinedChatrooms 获取用户加入的聊天室
获取聊天室详情 getChatroom 获取聊天室详细信息
创建聊天室 createChatroom 创建新聊天室
修改聊天室 updateChatroom 修改聊天室信息
删除聊天室 deleteChatroom 删除指定聊天室

👨‍👩‍👧‍👦 聊天室成员API

功能 API方法 描述
获取聊天室成员 getChatroomMembers 分页获取聊天室成员
添加聊天室成员 addChatroomMember 添加单个用户到聊天室
批量添加成员 addChatroomMembers 批量添加用户到聊天室
移除聊天室成员 removeChatroomMember 从聊天室移除单个用户
批量移除成员 removeChatroomMembers 从聊天室批量移除用户
获取聊天室管理员 getChatroomAdmins 获取聊天室管理员列表
添加聊天室管理员 addChatroomAdmin 设置聊天室管理员
移除聊天室管理员 removeChatroomAdmin 取消聊天室管理员

🚫 聊天室黑白名单API

功能 API方法 描述
获取聊天室黑名单 getChatroomBlockedUsers 查看聊天室黑名单
添加聊天室黑名单 addChatroomBlockedUsers 批量添加黑名单用户
移除聊天室黑名单 removeChatroomBlockedUsers 批量移除黑名单用户
获取聊天室白名单 getChatroomWhiteUsers 查看聊天室白名单
添加聊天室白名单 addChatroomWhiteUsers 批量添加白名单用户
移除聊天室白名单 removeChatroomWhiteUsers 批量移除白名单用户

🔇 聊天室禁言API

功能 API方法 描述
获取禁言列表 getChatroomMutedUsers 查看聊天室禁言列表
禁言聊天室成员 muteChatroomMembers 禁言指定聊天室成员
解除成员禁言 unmuteChatroomMembers 解除聊天室成员禁言
禁言全体成员 muteAllChatroomMembers 一键禁言全体成员
解除全员禁言 unmuteAllChatroomMembers 一键解除全员禁言

📢 聊天室公告API

功能 API方法 描述
获取聊天室公告 getChatroomAnnouncement 获取聊天室公告内容
修改聊天室公告 updateChatroomAnnouncement 修改聊天室公告

📝 使用示例

用户管理示例

// 创建用户
await easemobAPI.createUser({
  username: "testuser001",
  password: "123456", 
  nickname: "测试用户"
});

// 获取用户状态
await easemobAPI.getUserStatus("testuser001");

消息发送示例

// 发送文本消息
await easemobAPI.sendMessage({
  target_type: "users",
  target: ["testuser001"],
  msg: {
    type: "txt",
    msg: "你好,这是一条测试消息!"
  }
});

// 发送图片消息
await easemobAPI.sendMessage({
  target_type: "users", 
  target: ["testuser001"],
  msg: {
    type: "img",
    url: "https://example.com/image.jpg",
    filename: "image.jpg",
    size: 12345
  }
});

群组管理示例

// 创建群组
const group = await easemobAPI.createGroup({
  groupname: "测试群组",
  desc: "这是一个测试群组",
  owner: "testuser001",
  public: true,
  maxusers: 200,
  members: ["testuser002", "testuser003"]
});

// 添加群组成员
await easemobAPI.addGroupMembers(group.data.groupid, ["testuser004", "testuser005"]);

// 设置群组管理员
await easemobAPI.addGroupAdmin(group.data.groupid, "testuser002");

聊天室管理示例

// 创建聊天室
const chatroom = await easemobAPI.createChatroom({
  name: "测试聊天室",
  description: "这是一个测试聊天室",
  owner: "testuser001",
  maxusers: 1000
});

// 设置聊天室公告
await easemobAPI.updateChatroomAnnouncement(chatroom.data.id, "欢迎来到测试聊天室!");

🏗 项目结构

├── src/
│   ├── index.ts          # MCP服务器主文件
│   └── easemob-api.ts    # 完整环信API封装类
├── dist/                 # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
├── .env                  # 环境变量(需要创建)
├── env.example           # 环境变量示例
├── mcp-config.json       # MCP客户端配置示例
├── .gitignore           # Git忽略文件
└── README.md             # 项目文档

⚙️ 环境变量说明

变量名 必需 说明
EASEMOB_ORG_NAME ✅ 环信组织名称
EASEMOB_APP_NAME ✅ 环信应用名称
EASEMOB_APP_KEY ✅ 环信应用Key(Client ID)
EASEMOB_APP_SECRET ✅ 环信应用密钥(Client Secret)
EASEMOB_BASE_URL ❌ 环信API基础URL(可选,默认https://a1.easemob.com)

🛡️ 错误处理

项目包含完善的错误处理机制:

  • 网络错误: 自动重试和超时处理(30秒超时)
  • 认证错误: 自动刷新App Token,提前1分钟预刷新
  • 参数错误: 详细的参数验证和错误信息
  • API错误: 友好的中文错误信息,包含详细错误描述

⚠️ 注意事项

  1. API频率限制: 请注意环信API的调用频率限制
  2. Token管理: 系统会自动管理App Token的刷新,无需手动处理
  3. 数据中心: 请根据您的应用所在数据中心配置正确的API域名
  4. 安全性: 请妥善保管您的App Secret,不要泄露给第三方
  5. 消息类型: 支持文本、图片、语音、视频、文件、位置、透传、自定义等所有消息类型
  6. 并发处理: 建议使用连接池来优化并发请求性能

📄 许可证

MIT License

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目!如果您需要特定的功能或发现了bug,请随时联系我们。


这是一个功能完整的环信IM MCP服务器,涵盖了环信即时通讯的所有主要API功能,可以满足您的各种IM开发需求! 🎉