环信IM MCP服务器 - 完整版
这是一个完整集成了环信即时通讯(Easemob IM) RESTful API的MCP (Model Context Protocol) 服务器。涵盖环信IM的所有主要功能,包括用户管理、消息管理、群组管理、聊天室管理、好友关系、黑名单管理、用户属性管理、文件管理等。
🚀 功能特性
✅ 用户管理系统
- 用户操作: 注册单个/批量用户、获取用户信息、删除用户
- 用户状态: 获取在线状态、强制下线、修改密码
- 用户属性: 设置/获取/删除用户自定义属性
✅ 消息管理系统
- 消息发送: 支持文本、图片、语音、视频、文件、位置、透传、自定义消息
- 消息操作: 消息撤回、历史消息查询
- 消息类型: 单聊、群聊、聊天室消息全覆盖
✅ 群组管理系统
- 群组操作: 创建、获取、修改、删除群组
- 成员管理: 添加/移除成员、获取成员列表、转让群主
- 权限管理: 管理员设置、群主转让
- 黑白名单: 群组黑名单、白名单管理
- 禁言管理: 单个/批量/全体禁言和解禁
✅ 聊天室管理系统
- 聊天室操作: 创建、获取、修改、删除聊天室
- 成员管理: 添加/移除成员、管理员设置
- 权限控制: 黑白名单、禁言管理
- 公告管理: 设置和修改聊天室公告
✅ 用户关系管理
- 好友系统: 添加/删除好友、获取好友列表
- 黑名单: 添加/移除黑名单、查看黑名单
✅ 文件管理系统
- 文件操作: 文件上传、下载
- 文件类型: 支持图片、语音、视频、文档等各种文件类型
✅ 高级特性
- 自动认证: 智能Token管理和自动刷新
- 错误处理: 完善的错误处理和中文错误信息
- API覆盖: 涵盖环信IM REST API的所有主要功能
- 类型安全: 完整的TypeScript类型定义
📖 环信文档参考
本项目基于环信即时通讯 REST API 开发,详细API文档请参考:
🛠 快速开始
1. 安装依赖
2. 配置环信应用信息
复制环境变量示例文件:
编辑 .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
获取配置信息:
- 登录环信开发者控制台
- 选择您的应用
- 在"应用概览"页面获取所需配置信息
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错误: 友好的中文错误信息,包含详细错误描述
⚠️ 注意事项
- API频率限制: 请注意环信API的调用频率限制
- Token管理: 系统会自动管理App Token的刷新,无需手动处理
- 数据中心: 请根据您的应用所在数据中心配置正确的API域名
- 安全性: 请妥善保管您的App Secret,不要泄露给第三方
- 消息类型: 支持文本、图片、语音、视频、文件、位置、透传、自定义等所有消息类型
- 并发处理: 建议使用连接池来优化并发请求性能
📄 许可证
MIT License
🤝 贡献
欢迎提交Issue和Pull Request来改进这个项目!如果您需要特定的功能或发现了bug,请随时联系我们。
这是一个功能完整的环信IM MCP服务器,涵盖了环信即时通讯的所有主要API功能,可以满足您的各种IM开发需求! 🎉