Repository avatar
AI Tools
v0.2.1
active

alimail-admin-mcp

io.github.mfcompliance/alimail-admin-mcp

Manage Alibaba Mail (阿里邮箱) users, departments, groups and contacts via the admin OpenAPI

Documentation

alimail-admin-mcp

基于阿里邮箱开放平台 API 的 MCP(Model Context Protocol)服务。在 Claude、VS Code Copilot、Cursor 等 AI 客户端里,用自然语言管理企业邮箱的用户、部门、邮件组、公共通讯录、组织与域名,以及收信黑白名单、隔离区和审计日志。

⚠️ 本项目为非官方实现,与阿里云 / 阿里邮箱无隶属关系。它使用的应用凭证具有企业邮箱管理员级别的权限,请在充分理解风险后使用,并阅读免责声明。

特性

  • 66 个工具,分为 8 个工具集:
    • users:账号增删改查、别名、重置密码、邮箱设置、共享成员、安全手机、撤销登录态
    • departments:部门增删改查、层级链,以及可递归获取整棵部门树的组合工具
    • groups:邮件组增删改查与成员管理
    • contacts:公共联系人及分组管理,可递归获取分组树
    • org:组织信息、域名的添加 / 验证 / 删除
    • security:域级收信黑白名单、隔离区邮件的搜索 / 查看 / 放行 / 删除
    • audit:审计日志查询
    • login:生成免登录链接(默认不启用)
  • 默认只读:ALIMAIL_READ_ONLY=true 时只注册 30 个查询工具
  • 破坏性操作需两步确认:先返回预览和一次性 confirmToken,确认后才执行
  • 域名范围限制:ALIMAIL_ALLOWED_DOMAINS 可限定只能操作指定域名下的账号
  • 审计日志:所有写操作都记录为 JSON 行,密码、token 等敏感字段自动脱敏
  • 稳健的 API 客户端:token 缓存并提前刷新;令牌桶限流;429/5xx 自动退避重试,非幂等写操作不盲目重试;错误统一格式化并附带修复提示
  • 两种传输方式:stdio(默认)与 Streamable HTTP(--http)
  • Resources:alimail://departments/tree、alimail://users/{email};Prompts:onboard_employee(入职)、offboard_employee(离职)

准备工作:创建阿里邮箱应用

  1. 以管理员身份登录阿里邮箱域管后台,进入 高级应用 → API 开放平台(或“应用管理”),创建应用。
  2. 按最小权限原则授予 API 权限:只给启用的工具集授权(用户、部门、邮件组、公共联系人、组织与域名、收信规则、隔离区、审计日志、免登等)。只读场景只授读权限;需要写操作再授读写权限。权限名称以后台实际列出的为准。
  3. 记录应用的 client_id 与 client_secret。
  4. 确认企业所在集群的 API 地址(默认 https://alimail-cn.aliyuncs.com)。

免费版阿里邮箱不支持 API 开放平台。单个域内所有应用的 API 调用合计不能超过 40 次/秒。

配置

所有配置都通过环境变量提供(可参考 .env.example):

变量默认值说明
ALIMAIL_CLIENT_ID—必填,应用 ID
ALIMAIL_CLIENT_SECRET—必填,应用 Secret
ALIMAIL_API_BASEhttps://alimail-cn.aliyuncs.comAPI 地址,不同集群不能混用
ALIMAIL_READ_ONLYtrue设为 false 才会注册写操作和破坏性工具
ALIMAIL_TOOLSETS除 login 外的全部工具集启用的工具集,逗号分隔:users、departments、groups、contacts、org、security、audit、login;all 表示全部(含 login)
ALIMAIL_ALLOWED_DOMAINS空(不限制)限定可操作的邮箱域名,逗号分隔,子域名同样适用
ALIMAIL_MAX_QPS20本服务的请求速率上限(最大 40),需要给同域的其他应用留出余量
ALIMAIL_TIMEOUT_MS15000单次请求超时
ALIMAIL_AUDIT_LOG空(输出到 stderr)审计日志文件路径
MCP_HTTP_HOST127.0.0.1(Docker 镜像内为 0.0.0.0)HTTP 监听地址
MCP_HTTP_PORT3000HTTP 端口
MCP_AUTH_TOKEN空HTTP 模式下可选:设置后请求必须带 Authorization: Bearer <token>
MCP_ALLOWED_HOSTSlocalhost,127.0.0.1,[::1]允许的 Host 头,用于防御 DNS rebinding
LOG_LEVELinfodebug / info / warn / error

运行

方式一:npx(推荐)

已发布到 npm:@mfcompliance/alimail-admin-mcp,同时收录于 MCP Registry(io.github.mfcompliance/alimail-admin-mcp)。需要 Node.js 20 或更高版本。

ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy npx -y @mfcompliance/alimail-admin-mcp --check   # 验证凭证(只换取 token,不调用业务接口)
ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy npx -y @mfcompliance/alimail-admin-mcp --list-tools

也可以全局安装:npm i -g @mfcompliance/alimail-admin-mcp,之后直接运行 alimail-admin-mcp。

命令行参数:--http、--host、--port、--check、--list-tools、--version、--help。

方式二:从源码运行

npm ci
npm run build
ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy node dist/index.js --check

方式三:Docker

镜像由 GitHub Actions 自动构建并发布到 GitHub Container Registry,支持 linux/amd64 和 linux/arm64:

docker pull ghcr.io/mfcompliance/alimail-admin-mcp:latest
标签含义
latest、X.Y.Z、X.Y(X 从 1.0 开始)正式版本,在推送 vX.Y.Z 标签时发布
mainmain 分支的最新构建
sha-<短提交号>对应某次提交的构建

也可以在本地构建:

docker build -t alimail-admin-mcp:local .

下文示例使用 GHCR 镜像。如果是本地构建,把镜像名换成 alimail-admin-mcp:local 即可。

# 验证凭证
docker run --rm -e ALIMAIL_CLIENT_ID=xxx -e ALIMAIL_CLIENT_SECRET=yyy ghcr.io/mfcompliance/alimail-admin-mcp:latest --check

stdio 模式:由 MCP 客户端负责拉起容器,必须带 -i:

docker run -i --rm -e ALIMAIL_CLIENT_ID -e ALIMAIL_CLIENT_SECRET ghcr.io/mfcompliance/alimail-admin-mcp:latest

HTTP 模式:作为常驻服务运行:

cp .env.example .env    # 填入凭证
docker compose up -d --build
curl http://localhost:3000/healthz

docker-compose.yml 默认只把端口发布在 127.0.0.1 上,MCP 地址为 http://localhost:3000/mcp。

客户端配置

VS Code(.vscode/mcp.json)

使用 inputs 在运行时输入密钥,避免把密钥写进配置文件:

{
  "inputs": [
    { "id": "alimail-id", "type": "promptString", "description": "AliMail Client ID" },
    { "id": "alimail-secret", "type": "promptString", "description": "AliMail Client Secret", "password": true }
  ],
  "servers": {
    "alimail-admin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mfcompliance/alimail-admin-mcp"],
      "env": {
        "ALIMAIL_CLIENT_ID": "${input:alimail-id}",
        "ALIMAIL_CLIENT_SECRET": "${input:alimail-secret}",
        "ALIMAIL_READ_ONLY": "true"
      }
    }
  }
}

使用 Docker 时,把 command/args 换成 "command": "docker", "args": ["run", "-i", "--rm", "-e", "ALIMAIL_CLIENT_ID", "-e", "ALIMAIL_CLIENT_SECRET", "-e", "ALIMAIL_READ_ONLY", "ghcr.io/mfcompliance/alimail-admin-mcp:latest"];从源码运行时,换成 "command": "node", "args": ["/绝对路径/alimail-admin-mcp/dist/index.js"]。

连接 HTTP 模式的服务:

{
  "servers": {
    "alimail-admin": { "type": "http", "url": "http://localhost:3000/mcp" }
  }
}

Claude Desktop / Cursor / Cline

{
  "mcpServers": {
    "alimail-admin": {
      "command": "npx",
      "args": ["-y", "@mfcompliance/alimail-admin-mcp"],
      "env": {
        "ALIMAIL_CLIENT_ID": "xxx",
        "ALIMAIL_CLIENT_SECRET": "yyy",
        "ALIMAIL_READ_ONLY": "true"
      }
    }
  }
}

工具一览

✏️ 表示写操作(仅在 ALIMAIL_READ_ONLY=false 时注册),🔥 表示破坏性操作(同样需要关闭只读模式,并且需要两步确认)。

users

工具说明
list_users按 filter 查询用户,游标分页。filter 示例:(departmentId=xxx*)、(|(name=Jack)(email=*jack*))
get_user / get_users_by_ids获取单个用户 / 批量获取(最多 100 个)
get_mailbox_settings获取邮箱设置(外发限制、转发、附件大小等)
list_shared_members查询共享 / 委托成员
check_shared_access检查某用户能否访问指定共享账号
✏️ create_user创建账号;不传密码时自动生成,并强制下次登录修改
✏️ update_user更新资料、部门、状态(FREEZE 为冻结)
✏️ add_email_alias添加别名
✏️ update_mailbox_settings修改邮箱设置
✏️ add_shared_members / update_shared_members添加 / 更新共享成员权限(LOGIN、SEND_AS、SEND_ON_BEHALF)
✏️ bind_security_phone绑定安全手机
🔥 delete_user删除账号(不可逆)
🔥 reset_password重置密码(可自动生成)
🔥 remove_email_alias删除别名
🔥 remove_shared_members移除共享成员
🔥 unbind_security_phone解绑安全手机
🔥 revoke_user_sessions撤销全部登录态

departments

工具说明
get_department获取部门信息,$root 表示根部门
get_departments_by_ids批量获取(最多 100 个)
list_sub_departments / list_department_users直属子部门 / 直属成员(offset 分页)
get_department_chain层级链(支持单个或批量)
get_department_tree递归获取整棵部门树,自动分页;可设置深度、节点上限,可附带成员
✏️ create_department / update_department创建 / 更新(修改 parentId 即为移动部门)
🔥 delete_department删除部门;非空部门会删除失败,预览中会提示

groups

工具说明
list_groups按 filter 查询邮件组,游标分页。filter 示例:(name=*研发*)、(&(type=DYNAMIC)(status=FREEZE))
get_group按 ID 或邮箱获取邮件组
list_group_members查询成员邮箱(offset 分页,单页最多 10000)
✏️ create_group / update_group创建 / 更新(发信权限、投递审核、冻结等)
✏️ add_group_members批量添加成员(最多 50 个)
🔥 remove_group_members批量移除成员
🔥 delete_group删除邮件组

contacts

工具说明
get_shared_contact获取公共联系人
get_contact_folder / get_contact_folder_chain获取分组 / 分组层级链,$root 表示根分组
list_contact_subfolders / list_folder_contacts直属子分组 / 分组内联系人(offset 分页)
get_contact_folder_tree递归获取整棵分组树,可附带联系人
✏️ create_shared_contact / update_shared_contact创建 / 更新联系人(修改 folderId 即为移动)
✏️ create_contact_folder / update_contact_folder创建 / 更新分组(修改 parentId 即为移动)
🔥 delete_shared_contacts删除联系人(单次最多 20 个)
🔥 delete_contact_folder删除分组,预览显示联系人数和子分组数

org

工具说明
get_organization获取组织信息
list_domains / get_domain查询域名列表 / 单个域名(含域别名、MX 状态)
✏️ update_organization更新组织名称、联系方式、默认域名等
✏️ add_domain / verify_domain添加域名 / 验证域名所有权
🔥 delete_domain删除域名;主域名无法删除,预览中会提示

security

工具说明
list_allow_block_list查询域级收信白名单 / 黑名单
search_quarantine_messages按发件人、收件人、主题、时间搜索用户隔离区(隔离邮件保留 30 天)
get_quarantine_message / list_quarantine_attachments隔离邮件详情 / 附件列表
get_quarantine_attachment_url获取隔离附件的临时下载地址
🔥 add_allow_block_entries添加黑白名单条目(邮箱、域名、IP、IP 段、IP 归属地),对全组织生效
🔥 remove_allow_block_entries删除黑白名单条目
🔥 release_quarantine_message放行隔离邮件,投递到收件人邮箱
🔥 delete_quarantine_messages删除隔离邮件(移到已删除 / 企业回收站 / 永久删除)

audit

工具说明
query_audit_logs按时间、活动类型(登录、收发信、账号变更等)、操作者和属性查询审计日志

login

默认不启用,需要在 ALIMAIL_TOOLSETS 中显式加入 login(或使用 all),且需关闭只读模式。

工具说明
🔥 create_login_link生成一次性免登录链接(约 1 分钟有效),持有链接即可进入该用户邮箱

安全机制

两步确认

调用破坏性工具时:

  1. 第一次调用(不带 confirm)不会执行操作。它返回 status: "confirmation_required",同时附带目标对象的预览(例如被删除用户的姓名、邮箱、状态)和一个 confirmToken。
  2. AI 必须把预览展示给用户,并取得明确同意。
  3. 第二次调用使用完全相同的参数,并带上 confirm: true 和 confirmToken,这时才真正执行。

confirmToken 只能使用一次,5 分钟后过期,并与工具名和参数绑定:换了目标或修改了参数,token 即失效。

其他

  • 自动生成的密码只在执行结果中出现一次,不会写入日志或审计记录。
  • 设置 ALIMAIL_ALLOWED_DOMAINS 后,所有针对单个用户的操作都会检查目标所在域名。用 ID 定位用户时,服务会先查询出邮箱再做检查。创建用户、添加别名、共享成员中的地址也会检查。邮件组、隔离区、免登链接、按操作者查询审计日志,以及添加 / 验证 / 删除域名,同样按目标邮箱或域名检查。列表类查询(list_users、list_groups 等)、组织级设置(组织信息、收信黑白名单)、公共联系人以及邮件组成员地址不受此限制。
  • HTTP 模式:
    • 默认只监听 127.0.0.1,并校验 Host 头以防御 DNS rebinding。
    • 如果监听在非回环地址上又没有设置 MCP_AUTH_TOKEN,启动时会输出警告。
    • 不要把未加认证的端口暴露到局域网或公网:能访问这个端口的人,就能以邮箱管理员身份执行操作。
  • HTTP 模式是无状态的:每个请求都会新建 MCP 会话。token 缓存、限流、确认令牌和审计日志在进程内共享。

开发

npm ci
npm run typecheck
npm test          # vitest;所有 HTTP 请求均为模拟,不访问真实环境
npm run build
npm run inspect   # 使用 MCP Inspector 调试(需先设置凭证环境变量)

目录结构:

src/
  index.ts            CLI 入口
  config.ts           环境变量校验
  server.ts           组装 McpServer
  client/             token、限流、HTTP、分页、错误
  guard/              两步确认、域名范围、脱敏、审计
  tools/              registry、tree(通用树遍历)及各工具集
  resources/ prompts/
  transports/         stdio、Streamable HTTP
test/                 单元测试与端到端测试(InMemory 及 HTTP)

新增工具集的步骤:

  1. 在 src/config.ts 的 TOOLSETS 中登记名称。
  2. 新建 src/tools/<name>.ts,用 defineTool 定义工具。
  3. 在 src/server.ts 的 ALL_TOOLS 中注册。

接口的字段、分页方式和所需权限,请以官方文档为准。

发布

.github/workflows/docker.yml 的行为:

  • Pull Request:运行测试,并构建镜像,但不推送。
  • 推送到 main:测试通过后推送 main 和 sha-* 标签。
  • 推送 v* 标签:推送版本号标签和 latest,同时附带构建来源证明(build provenance attestation)。

.github/workflows/npm.yml 在推送 v* 标签时发布 npm 包:先校验标签与 package.json、server.json 版本一致,再通过 Trusted Publishing(OIDC,无需 NPM_TOKEN)发布,并附带 provenance。预发布版本(如 0.2.0-beta.1)使用 next 标签,不影响 latest。如果该版本已在 npm 上,会跳过 npm 发布,因此重跑 workflow 是安全的。

npm 发布成功后,同一个 workflow 会用 GitHub OIDC 登录 MCP Registry,把 server.json 发布为 io.github.mfcompliance/alimail-admin-mcp(预发布版本不发布)。Registry 通过 package.json 里的 mcpName 校验 npm 包归属,因此 mcpName 必须与 server.json 的 name 一致。

发布新版本的步骤:

npm version 0.3.0 --no-git-tag-version   # 同步修改 package.json、package-lock.json 和 server.json;再手动更新 CHANGELOG.md
git commit -am "chore: release v0.3.0"
git tag v0.3.0 && git push origin main v0.3.0

首次推送后,GHCR 上的包默认是私有的。如果要让别人免登录拉取,需要在仓库的 Packages → 包设置 → Change visibility 中改为 Public。

免责声明

  • 本项目为社区开发的非官方工具,与阿里巴巴集团、阿里云及阿里邮箱无任何隶属、合作或背书关系。“阿里邮箱”“Alibaba Mail”等名称和商标归其各自所有者所有,本项目仅用于说明兼容对象。
  • 本软件按“原样”提供,不附带任何明示或默示的担保,详见 MIT 许可。作者和贡献者不对因使用本软件导致的任何损失承担责任,包括数据丢失、账号误删或被停用、邮件服务中断、安全事件。
  • 写操作和破坏性操作可能由 AI 模型根据自然语言指令发起,模型可能误解指令或产生错误参数。两步确认、只读模式、域名限制等机制只能降低风险,不能完全消除风险。请先在测试域名或测试账号上验证,执行前仔细核对预览内容,并在生产环境中按最小权限原则配置应用权限。
  • 本工具会处理员工姓名、邮箱、手机号、登录记录等个人信息和企业数据。使用者应自行确保符合所在组织的内部制度和适用的法律法规,例如《个人信息保护法》《数据安全法》,并妥善保管应用凭证和审计日志。
  • 阿里邮箱开放平台的接口、权限和限额可能随时变化,以官方文档为准。

许可

MIT

NPM
@mfcompliance/alimail-admin-mcp
Install Command
npm install @mfcompliance/alimail-admin-mcp