AliMail Admin MCP
Use natural language in MCP-compatible AI clients to administer an Alibaba Mail enterprise organization, with read-only defaults and safety guards.
Users: list/get/create/update/delete accounts, aliases, reset passwords, mailbox settings, shared members, security phone, revoke sessions.
Departments: CRUD, hierarchy chains, sub-departments, members, and recursive department trees.
Groups: manage mailing groups and their members.
Contacts: manage shared contacts and contact folder trees.
Org & domains: view/update organization info, add/verify/delete domains.
Security: domain-level allow/block lists and quarantine message search, view, release, delete.
Audit: query audit logs by time, activity type, operator, and attributes.
Login links (opt-in): generate one-time passwordless login links.
Safety: read-only mode by default, two-step confirmation for destructive actions, allowed-domain restrictions, and redacted audit logging.
Transports: run via stdio or Streamable HTTP, with resources and prompts for onboarding/offboarding.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AliMail Admin MCP show me the full department tree for our company domain"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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(离职)
Related MCP server: proofpoint-essentials-mcp
准备工作:创建阿里邮箱应用
以管理员身份登录阿里邮箱域管后台,进入 高级应用 → API 开放平台(或“应用管理”),创建应用。
按最小权限原则授予 API 权限:只给启用的工具集授权(用户、部门、邮件组、公共联系人、组织与域名、收信规则、隔离区、审计日志、免登等)。只读场景只授读权限;需要写操作再授读写权限。权限名称以后台实际列出的为准。
记录应用的
client_id与client_secret。确认企业所在集群的 API 地址(默认
https://alimail-cn.aliyuncs.com)。
免费版阿里邮箱不支持 API 开放平台。单个域内所有应用的 API 调用合计不能超过 40 次/秒。
配置
所有配置都通过环境变量提供(可参考 .env.example):
变量 | 默认值 | 说明 |
| — | 必填,应用 ID |
| — | 必填,应用 Secret |
|
| API 地址,不同集群不能混用 |
|
| 设为 |
| 除 | 启用的工具集,逗号分隔: |
| 空(不限制) | 限定可操作的邮箱域名,逗号分隔,子域名同样适用 |
|
| 本服务的请求速率上限(最大 40),需要给同域的其他应用留出余量 |
|
| 单次请求超时 |
| 空(输出到 stderr) | 审计日志文件路径 |
|
| HTTP 监听地址 |
|
| HTTP 端口 |
| 空 | HTTP 模式下可选:设置后请求必须带 |
|
| 允许的 Host 头,用于防御 DNS rebinding |
|
|
|
运行
方式一: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标签 | 含义 |
| 正式版本,在推送 |
|
|
| 对应某次提交的构建 |
也可以在本地构建:
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 --checkstdio 模式:由 MCP 客户端负责拉起容器,必须带 -i:
docker run -i --rm -e ALIMAIL_CLIENT_ID -e ALIMAIL_CLIENT_SECRET ghcr.io/mfcompliance/alimail-admin-mcp:latestHTTP 模式:作为常驻服务运行:
cp .env.example .env # 填入凭证
docker compose up -d --build
curl http://localhost:3000/healthzdocker-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
工具 | 说明 |
| 按 filter 查询用户,游标分页。filter 示例: |
| 获取单个用户 / 批量获取(最多 100 个) |
| 获取邮箱设置(外发限制、转发、附件大小等) |
| 查询共享 / 委托成员 |
| 检查某用户能否访问指定共享账号 |
✏️ | 创建账号;不传密码时自动生成,并强制下次登录修改 |
✏️ | 更新资料、部门、状态( |
✏️ | 添加别名 |
✏️ | 修改邮箱设置 |
✏️ | 添加 / 更新共享成员权限(LOGIN、SEND_AS、SEND_ON_BEHALF) |
✏️ | 绑定安全手机 |
🔥 | 删除账号(不可逆) |
🔥 | 重置密码(可自动生成) |
🔥 | 删除别名 |
🔥 | 移除共享成员 |
🔥 | 解绑安全手机 |
🔥 | 撤销全部登录态 |
departments
工具 | 说明 |
| 获取部门信息, |
| 批量获取(最多 100 个) |
| 直属子部门 / 直属成员(offset 分页) |
| 层级链(支持单个或批量) |
| 递归获取整棵部门树,自动分页;可设置深度、节点上限,可附带成员 |
✏️ | 创建 / 更新(修改 |
🔥 | 删除部门;非空部门会删除失败,预览中会提示 |
groups
工具 | 说明 |
| 按 filter 查询邮件组,游标分页。filter 示例: |
| 按 ID 或邮箱获取邮件组 |
| 查询成员邮箱(offset 分页,单页最多 10000) |
✏️ | 创建 / 更新(发信权限、投递审核、冻结等) |
✏️ | 批量添加成员(最多 50 个) |
🔥 | 批量移除成员 |
🔥 | 删除邮件组 |
contacts
工具 | 说明 |
| 获取公共联系人 |
| 获取分组 / 分组层级链, |
| 直属子分组 / 分组内联系人(offset 分页) |
| 递归获取整棵分组树,可附带联系人 |
✏️ | 创建 / 更新联系人(修改 |
✏️ | 创建 / 更新分组(修改 |
🔥 | 删除联系人(单次最多 20 个) |
🔥 | 删除分组,预览显示联系人数和子分组数 |
org
工具 | 说明 |
| 获取组织信息 |
| 查询域名列表 / 单个域名(含域别名、MX 状态) |
✏️ | 更新组织名称、联系方式、默认域名等 |
✏️ | 添加域名 / 验证域名所有权 |
🔥 | 删除域名;主域名无法删除,预览中会提示 |
security
工具 | 说明 |
| 查询域级收信白名单 / 黑名单 |
| 按发件人、收件人、主题、时间搜索用户隔离区(隔离邮件保留 30 天) |
| 隔离邮件详情 / 附件列表 |
| 获取隔离附件的临时下载地址 |
🔥 | 添加黑白名单条目(邮箱、域名、IP、IP 段、IP 归属地),对全组织生效 |
🔥 | 删除黑白名单条目 |
🔥 | 放行隔离邮件,投递到收件人邮箱 |
🔥 | 删除隔离邮件(移到已删除 / 企业回收站 / 永久删除) |
audit
工具 | 说明 |
| 按时间、活动类型(登录、收发信、账号变更等)、操作者和属性查询审计日志 |
login
默认不启用,需要在 ALIMAIL_TOOLSETS 中显式加入 login(或使用 all),且需关闭只读模式。
工具 | 说明 |
🔥 | 生成一次性免登录链接(约 1 分钟有效),持有链接即可进入该用户邮箱 |
安全机制
两步确认
调用破坏性工具时:
第一次调用(不带
confirm)不会执行操作。它返回status: "confirmation_required",同时附带目标对象的预览(例如被删除用户的姓名、邮箱、状态)和一个confirmToken。AI 必须把预览展示给用户,并取得明确同意。
第二次调用使用完全相同的参数,并带上
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)新增工具集的步骤:
在
src/config.ts的TOOLSETS中登记名称。新建
src/tools/<name>.ts,用defineTool定义工具。在
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 模型根据自然语言指令发起,模型可能误解指令或产生错误参数。两步确认、只读模式、域名限制等机制只能降低风险,不能完全消除风险。请先在测试域名或测试账号上验证,执行前仔细核对预览内容,并在生产环境中按最小权限原则配置应用权限。
本工具会处理员工姓名、邮箱、手机号、登录记录等个人信息和企业数据。使用者应自行确保符合所在组织的内部制度和适用的法律法规,例如《个人信息保护法》《数据安全法》,并妥善保管应用凭证和审计日志。
阿里邮箱开放平台的接口、权限和限额可能随时变化,以官方文档为准。
许可
Available Tools
11 toolsget_department获取部门信息ARead-onlyIdempotent
根据部门 ID 获取部门信息;id 传 $root 返回组织根部门。
Inputs: id (required), select.
get_department_chain获取部门层级链ARead-onlyIdempotent
获取从根部门到目标部门的完整层级链。传 id 查询单个,传 ids 批量查询(最多 100 个)。
Inputs: id, ids.
get_departments_by_ids批量获取部门信息ARead-onlyIdempotent
根据部门 ID 列表批量获取部门信息(最多 100 个),不存在的 ID 不返回。
Inputs: ids (required), select.
get_department_tree获取部门树ARead-onlyIdempotent
从指定部门(默认根部门)递归获取完整部门树,自动处理分页。可选包含每个部门的直属成员。大型组织请设置 maxDepth / maxNodes 控制规模,结果中 truncated=true 表示被截断。
Inputs: rootId, maxDepth, maxNodes, includeUsers, +1 more.
get_mailbox_settings获取邮箱设置ARead-onlyIdempotent
获取用户邮箱设置(外部收发信限制、自动转发、附件大小、收件人数等)。字段多为可选字段,可用 select 指定,如 forbidSendMailToOutside,forwardingMode,attachmentSize。
Inputs: user (required), select.
get_user获取用户信息CRead-onlyIdempotent
根据用户 ID 或邮箱获取用户详情。
Inputs: user (required), select.
get_users_by_ids批量获取用户信息ARead-onlyIdempotent
根据用户 ID 列表批量获取用户信息(最多 100 个),不存在的 ID 不返回。
Inputs: ids (required), select.
list_department_users查询部门成员ARead-onlyIdempotent
查询指定部门的直属成员(offset/limit 分页,limit 最大 100)。如需含子部门成员,可用 list_users 的 filter (departmentId=xxx*)。
Inputs: id (required), limit, offset, select, +1 more.
list_sub_departments查询子部门ARead-onlyIdempotent
查询指定部门的直属子部门(offset/limit 分页,limit 最大 100)。需要整棵树请用 get_department_tree。
Inputs: id (required), limit, offset, select, +1 more.
list_users查询用户列表ARead-onlyIdempotent
按 filter 表达式查询组织内用户,游标分页(单页最多 100)。 filter 支持字段:email、name、nickname、employeeNo、status、domain、employeeType、delegateType、departmentId、jobTitle、workLocation、homeLocation、info、managerId、isSharedWithOthers。 示例:(departmentId=xxx) 直属成员;(departmentId=xxx*) 含子部门;(|(name=Jack)(email=jack));(&(employeeType=SERVICE)(email=abc));(&(departmentId=xxx)(!(status=FREEZE)))。 返回 hasMore=true 时用 nextCursor 继续翻页。
Inputs: size, order, cursor, filter, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The get/list department trio (get_department, get_departments_by_ids, get_department_chain) and the tree-vs-subdepartment pair (get_department_tree vs list_sub_departments) have some conceptual overlap, but descriptions explicitly cross-reference each other ("需要整棵树请用 get_department_tree") to route the agent correctly. Single-vs-batch (get_user vs get_users_by_ids) and user-vs-department listing are clearly distinguished.
All 11 tools follow a strict verb_noun snake_case convention: list_*, get_*, with suffixes clearly indicating batch (_by_ids, _ids). No mixing of styles or casing.
11 tools is well within the ideal 3-15 range for an org directory/mailbox admin server. Each tool earns its place by covering a distinct access pattern (single, batch, tree, filter, chain, settings).
The surface is entirely read-only: there is no create/update/delete for departments or users, and no update_mailbox_settings despite get_mailbox_settings existing, which is a notable gap for an 'Admin' server. Read coverage (single, batch, tree, filter, chain, shared accounts, mailbox settings) is otherwise solid.
Maintenance
Related MCP Connectors
Business email on your domain for AI agents: read, draft and send with the permissions you choose.
Give AI agents secure access to your email via private aliases with dedicated mailbox storage.
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
AI agents read & send email, manage mailboxes, domains and webhooks via the QMailing API.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Migadu email hosting services through natural language, including creating mailboxes, setting up aliases, configuring autoresponders, and handling bulk operations efficiently.3531 PyPI17MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage MSP-multi-tenant email security: organizations, domains, users, licensing, features, subscription packages, and email flow reporting.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants and compatible clients to securely search, read, send, reply, forward, organize, and bulk-delete email across multiple mailboxes, with automatic SMTP configuration and AES-256-encrypted credential storage.931 npmMIT
- AlicenseBqualityBmaintenanceEnables AI assistants and other MCP clients to manage mailboxes, domains, routing rules, app passwords, and account credit through the Purelymail API, with optional read-only exposure.19405 npm1MIT